agent-relay 3.2.9 → 3.2.11

package/packages/sdk/src/workflows/default-logger.ts

@@ -0,0 +1,120 @@
+import chalk from 'chalk';
+import type { WorkflowEvent, WorkflowEventListener } from './runner.js';
+
+export type LogLevel = 'verbose' | 'normal' | 'quiet' | false;
+
+const noop: WorkflowEventListener = () => {};
+
+/**
+ * Create a default event logger that writes workflow progress to the console.
+ *
+ * @param level - Log verbosity: "verbose" | "normal" (default) | "quiet" | false (no-op)
+ */
+export function createDefaultEventLogger(level: LogLevel = 'normal'): WorkflowEventListener {
+  if (level === false) return noop;
+
+  return (event: WorkflowEvent) => {
+    switch (event.type) {
+      // ── Run lifecycle ──
+      case 'run:started':
+        if (level !== 'quiet') {
+          console.log(chalk.cyan(`[workflow] run ${event.runId.slice(0, 8)}...`));
+        }
+        break;
+
+      case 'run:completed':
+        console.log(chalk.green(`[workflow] completed`));
+        break;
+
+      case 'run:failed':
+        console.log(chalk.red(`[workflow] FAILED: ${event.error}`));
+        break;
+
+      case 'run:cancelled':
+        if (level !== 'quiet') {
+          console.log(chalk.yellow(`[workflow] cancelled`));
+        }
+        break;
+
+      // ── Step lifecycle ──
+      case 'step:started':
+        if (level !== 'quiet') {
+          console.log(chalk.blue(`  ● ${event.stepName} — started`));
+        }
+        break;
+
+      case 'step:completed':
+        if (level !== 'quiet') {
+          console.log(chalk.green(`  ✓ ${event.stepName} — completed`));
+        }
+        break;
+
+      case 'step:failed':
+        console.log(chalk.red(`  ✗ ${event.stepName} — FAILED: ${event.error}`));
+        break;
+
+      case 'step:skipped':
+        if (level !== 'quiet') {
+          console.log(chalk.gray(`  ○ ${event.stepName} — skipped`));
+        }
+        break;
+
+      case 'step:retrying':
+        if (level !== 'quiet') {
+          console.log(chalk.yellow(`  ↻ ${event.stepName} — retrying (attempt ${event.attempt})`));
+        }
+        break;
+
+      case 'step:nudged':
+        if (level !== 'quiet') {
+          console.log(chalk.yellow(`  ⚡ ${event.stepName} — nudged (${event.nudgeCount})`));
+        }
+        break;
+
+      case 'step:agent-report': {
+        if (level !== 'quiet') {
+          const r = event.report;
+          const parts: string[] = [];
+          if (r.model) parts.push(r.model);
+          if (r.cost != null) parts.push(`$${r.cost.toFixed(2)}`);
+          if (r.tokens) parts.push(`${r.tokens.input}+${r.tokens.output} tokens`);
+          parts.push(`${r.errors.length} errors`);
+          console.log(chalk.dim(`  📊 ${event.stepName} — ${parts.join(' · ')}`));
+        }
+        break;
+      }
+
+      // ── Broker-level events (verbose only) ──
+      case 'broker:event':
+        if (level === 'verbose') {
+          console.log(chalk.dim(`  [broker] ${JSON.stringify(event.event)}`));
+        }
+        break;
+
+      // ── Other events (verbose only) ──
+      case 'step:owner-assigned':
+        if (level === 'verbose') {
+          console.log(chalk.dim(`  ${event.stepName} — owner: ${event.ownerName}, specialist: ${event.specialistName}`));
+        }
+        break;
+
+      case 'step:review-completed':
+        if (level === 'verbose') {
+          console.log(chalk.dim(`  ${event.stepName} — review: ${event.decision} by ${event.reviewerName}`));
+        }
+        break;
+
+      case 'step:owner-timeout':
+        if (level !== 'quiet') {
+          console.log(chalk.yellow(`  ⏱ ${event.stepName} — owner timeout (${event.ownerName})`));
+        }
+        break;
+
+      case 'step:force-released':
+        if (level === 'verbose') {
+          console.log(chalk.dim(`  ${event.stepName} — force-released`));
+        }
+        break;
+    }
+  };
+}

package/packages/sdk/src/workflows/index.ts

@@ -1,6 +1,8 @@
 export * from './types.js';
 export * from './runner.js';
 export * from './custom-steps.js';
+export * from './cli-session-collector.js';
+export * from './run-summary-table.js';
 export {
   Models,
   ClaudeModels,
@@ -22,3 +24,5 @@ export * from './state.js';
 export * from './templates.js';
 export { WorkflowTrajectory, type StepOutcome } from './trajectory.js';
 export { formatDryRunReport } from './dry-run-format.js';
+export { createWorkflowRenderer, type WorkflowRenderer } from './listr-renderer.js';
+export { createDefaultEventLogger } from './default-logger.js';

package/packages/sdk/src/workflows/listr-renderer.ts

@@ -0,0 +1,278 @@
+import chalk from 'chalk';
+import type { ListrTask } from 'listr2';
+import type { WorkflowEvent, WorkflowEventListener } from './runner.js';
+
+// Filter console.log while listr owns the terminal.
+// Blocks [broker] noise and [workflow HH:MM] timing lines, but lets the
+// observer URL and channel name through so users can track the run.
+function installOutputFilter(): () => void {
+  const orig = console.log.bind(console);
+  console.log = (...args: unknown[]) => {
+    const str = String(args[0] ?? '');
+    // Always show the observer URL and channel so users can follow the run
+    if (str.includes('Observer:') || str.includes('agentrelay.dev') || str.includes('Channel: wf-')) {
+      orig(...args);
+      return;
+    }
+    // Block [broker] lines and [workflow HH:MM] timing lines
+    if (/\[broker\]/.test(str) || /\[workflow\s+\d{2}:\d{2}\]/.test(str)) return;
+    orig(...args);
+  };
+  return () => {
+    console.log = orig;
+  };
+}
+
+interface RenderableTask {
+  title: string;
+  output: string;
+}
+
+interface StepHandle {
+  resolve: () => void;
+  reject: (error: Error) => void;
+  setOutput: (text: string) => void;
+  markSkipped: () => void;
+}
+
+export interface WorkflowRenderer {
+  /** Pass this to `.run({ onEvent })` in your TypeScript workflow. */
+  onEvent: WorkflowEventListener;
+  /** Start the listr renderer. Run this concurrently with your workflow. */
+  start: () => Promise<void>;
+  /** Restore console.log after the workflow finishes. */
+  unmount: () => void;
+}
+
+/**
+ * Creates a listr2-based renderer for TypeScript workflows.
+ *
+ * @example
+ * ```typescript
+ * import { workflow, createWorkflowRenderer } from '@agent-relay/sdk/workflows';
+ *
+ * const renderer = createWorkflowRenderer();
+ * const [result] = await Promise.all([
+ *   workflow('my-workflow').step(...).run({ onEvent: renderer.onEvent }),
+ *   renderer.start(),
+ * ]);
+ * renderer.unmount();
+ * ```
+ */
+export function createWorkflowRenderer(): WorkflowRenderer {
+  const stepHandles = new Map<string, StepHandle>();
+
+  let resolveWorkflow!: () => void;
+  let rejectWorkflow!: (error: Error) => void;
+  const workflowDone = new Promise<void>((resolve, reject) => {
+    resolveWorkflow = resolve;
+    rejectWorkflow = reject;
+  });
+  // Prevent unhandled rejection if run:failed fires before the header task
+  // reaches `await workflowDone`.
+  workflowDone.catch(() => {});
+
+  let setHeader: (text: string) => void = () => {};
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let listr: any = null;
+  const pendingAdds: ListrTask[] = [];
+
+  async function ensureListr(): Promise<any> {
+    if (listr) return listr;
+    const { Listr } = await import('listr2');
+    listr = new (Listr as any)(
+      [
+        {
+          title: chalk.dim('Workflow starting...'),
+          task: async (_ctx, task): Promise<void> => {
+            setHeader = (text: string): void => {
+              task.title = text;
+            };
+            await workflowDone;
+          },
+        } as ListrTask,
+      ],
+      {
+        concurrent: true,
+        renderer: process.stdout.isTTY ? 'default' : 'verbose',
+        rendererOptions: {
+          collapseErrors: false,
+          showErrorMessage: true,
+      },
+    },
+    );
+    for (const task of pendingAdds) listr.add(task);
+    pendingAdds.length = 0;
+    return listr;
+  }
+
+  const addTask = (task: ListrTask): void => {
+    if (listr) listr.add(task);
+    else pendingAdds.push(task);
+  };
+
+  const onEvent: WorkflowEventListener = (event: WorkflowEvent) => {
+    switch (event.type) {
+      case 'run:started': {
+        setHeader(chalk.dim(`[workflow] run ${event.runId.slice(0, 8)}...`));
+        break;
+      }
+
+      case 'step:started': {
+        let resolveStep!: () => void;
+        let rejectStep!: (error: Error) => void;
+        let taskRef: RenderableTask | null = null;
+        let skipped = false;
+
+        const done = new Promise<void>((resolve, reject) => {
+          resolveStep = resolve;
+          rejectStep = reject;
+        });
+        // Prevent unhandled rejection if the step fails before the listr
+        // task function has started and reached `await done`.
+        done.catch(() => {});
+
+        stepHandles.set(event.stepName, {
+          resolve: resolveStep,
+          reject: rejectStep,
+          setOutput: (text: string) => {
+            if (taskRef) taskRef.output = text;
+          },
+          markSkipped: () => {
+            skipped = true;
+            if (taskRef) taskRef.title = chalk.dim(`${event.stepName} (skipped)`);
+          },
+        });
+
+        addTask({
+          title: chalk.white(event.stepName),
+          task: async (_ctx, task): Promise<void> => {
+            taskRef = task as RenderableTask;
+            if (skipped) taskRef.title = chalk.dim(`${event.stepName} (skipped)`);
+            await done;
+          },
+          rendererOptions: { persistentOutput: true },
+        } as ListrTask);
+        break;
+      }
+
+      case 'step:owner-assigned': {
+        const handle = stepHandles.get(event.stepName);
+        if (handle) {
+          handle.setOutput(
+            chalk.dim(`> Owner: ${event.ownerName}`) +
+              (event.specialistName ? chalk.dim(` · specialist: ${event.specialistName}`) : ''),
+          );
+        }
+        break;
+      }
+
+      case 'step:retrying': {
+        stepHandles.get(event.stepName)?.setOutput(chalk.yellow(`Retrying (attempt ${event.attempt})`));
+        break;
+      }
+
+      case 'step:nudged': {
+        stepHandles.get(event.stepName)?.setOutput(chalk.dim(`> Nudge #${event.nudgeCount}`));
+        break;
+      }
+
+      case 'step:force-released': {
+        stepHandles.get(event.stepName)?.setOutput(chalk.yellow('> Force-released'));
+        break;
+      }
+
+      case 'step:review-completed': {
+        stepHandles
+          .get(event.stepName)
+          ?.setOutput(chalk.dim(`> Review: ${event.decision} by ${event.reviewerName}`));
+        break;
+      }
+
+      case 'step:owner-timeout': {
+        stepHandles
+          .get(event.stepName)
+          ?.setOutput(chalk.red(`> Owner ${event.ownerName} timed out`));
+        break;
+      }
+
+      case 'step:agent-report': {
+        const handle = stepHandles.get(event.stepName);
+        if (handle) {
+          const model = event.report.model ? `:${event.report.model}` : '';
+          handle.setOutput(chalk.dim(`> Report collected (${event.report.cli}${model})`));
+        }
+        break;
+      }
+
+      case 'step:completed': {
+        stepHandles.get(event.stepName)?.resolve();
+        break;
+      }
+
+      case 'step:skipped': {
+        const handle = stepHandles.get(event.stepName);
+        if (handle) {
+          handle.markSkipped();
+          handle.resolve();
+        } else {
+          // Step was skipped without ever being started (downstream of a failure).
+          addTask({
+            title: chalk.dim(`${event.stepName} (skipped)`),
+            task: async (): Promise<void> => {},
+            rendererOptions: { persistentOutput: true },
+          } as ListrTask);
+        }
+        break;
+      }
+
+      case 'step:failed': {
+        stepHandles.get(event.stepName)?.reject(new Error(event.error ?? 'Step failed'));
+        break;
+      }
+
+      case 'run:completed': {
+        setHeader(chalk.green('Workflow completed'));
+        resolveWorkflow();
+        break;
+      }
+
+      case 'run:failed': {
+        setHeader(chalk.red(`Workflow failed: ${event.error ?? 'unknown error'}`));
+        rejectWorkflow(new Error(event.error ?? 'Workflow failed'));
+        break;
+      }
+
+      case 'run:cancelled': {
+        setHeader(chalk.yellow('Workflow cancelled'));
+        resolveWorkflow();
+        break;
+      }
+
+      case 'broker:event':
+        break;
+
+      default: {
+        const _exhaustive: never = event;
+        void _exhaustive;
+      }
+    }
+  };
+
+  let restoreConsole: (() => void) | undefined;
+
+  return {
+    onEvent,
+    start: async () => {
+      restoreConsole = installOutputFilter();
+      const l = await ensureListr();
+      return l.run().catch(() => {
+        // Step failures are already represented in the workflow result.
+      });
+    },
+    unmount: () => {
+      restoreConsole?.();
+      restoreConsole = undefined;
+    },
+  };
+}

package/packages/sdk/src/workflows/run-summary-table.ts

@@ -0,0 +1,110 @@
+import type { CliSessionReport } from './cli-session-collector.js';
+import type { StepOutcome } from './trajectory.js';
+
+function formatCurrency(value: number | null | undefined): string {
+  return typeof value === 'number' ? `$${value.toFixed(2)}` : '--';
+}
+
+function formatTokens(report: CliSessionReport | undefined): string {
+  if (!report?.tokens) return '--';
+  const total = report.tokens.input + report.tokens.output + report.tokens.cacheRead;
+  return total.toLocaleString('en-US');
+}
+
+function formatDuration(durationMs: number | null | undefined): string {
+  if (typeof durationMs !== 'number' || !Number.isFinite(durationMs)) return '--';
+  if (durationMs < 1000) return `${durationMs}ms`;
+
+  const totalSeconds = Math.round(durationMs / 1000);
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
+}
+
+function truncate(value: string, length: number): string {
+  if (value.length <= length) return value;
+  if (length <= 1) return value.slice(0, length);
+  return `${value.slice(0, length - 1)}…`;
+}
+
+function pad(value: string, width: number, align: 'left' | 'right' = 'left'): string {
+  return align === 'right' ? value.padStart(width, ' ') : value.padEnd(width, ' ');
+}
+
+function formatErrors(outcome: StepOutcome, report: CliSessionReport | undefined): string {
+  const count = report?.errors.length ?? 0;
+  if (count === 0) return outcome.status === 'failed' && outcome.error ? '1' : '--';
+  if (outcome.status === 'completed') return `${count} (fixed)`;
+  return String(count);
+}
+
+export function formatRunSummaryTable(
+  outcomes: StepOutcome[],
+  reports: Map<string, CliSessionReport>
+): string {
+  // Only show the Cost column when at least one report has reliable cost data
+  // (currently only OpenCode populates cost; Claude and Codex return null)
+  const hasCost = Array.from(reports.values()).some((r) => typeof r.cost === 'number' && r.cost > 0);
+
+  const headers = hasCost
+    ? ['Step', 'Status', 'Model', 'Cost', 'Tokens', 'Duration', 'Errors']
+    : ['Step', 'Status', 'Model', 'Tokens', 'Duration', 'Errors'];
+  const widths = hasCost
+    ? [20, 6, 16, 8, 10, 10, 10]
+    : [20, 6, 16, 10, 10, 10];
+  const lines: string[] = [];
+
+  lines.push(headers.map((h, i) => {
+    const align = i <= 2 ? 'left' : 'right';
+    return pad(h, widths[i], align);
+  }).join('  '));
+
+  let totalCost = 0;
+  let totalTokens = 0;
+  let totalDurationMs = 0;
+
+  for (const outcome of outcomes) {
+    const report = reports.get(outcome.name);
+    const reportDuration = report?.durationMs ?? outcome.durationMs;
+    const reportTokens = report?.tokens
+      ? report.tokens.input + report.tokens.output + report.tokens.cacheRead
+      : 0;
+
+    if (typeof report?.cost === 'number') totalCost += report.cost;
+    totalTokens += reportTokens;
+    if (typeof reportDuration === 'number') totalDurationMs += reportDuration;
+
+    const cols: string[] = [
+      pad(truncate(outcome.name, widths[0]), widths[0]),
+      pad(outcome.status === 'failed' ? 'FAIL' : outcome.status === 'completed' ? 'pass' : 'skip', widths[1]),
+      pad(truncate(report?.model ?? '--', widths[2]), widths[2]),
+    ];
+    if (hasCost) cols.push(pad(formatCurrency(report?.cost), widths[3], 'right'));
+    const tokenIdx = hasCost ? 4 : 3;
+    cols.push(pad(formatTokens(report), widths[tokenIdx], 'right'));
+    cols.push(pad(formatDuration(reportDuration), widths[tokenIdx + 1], 'right'));
+    cols.push(pad(formatErrors(outcome, report), widths[tokenIdx + 2], 'right'));
+
+    lines.push(cols.join('  '));
+
+    if (outcome.status === 'failed') {
+      const firstError = report?.errors[0];
+      if (firstError) {
+        lines.push(`  └─ Error [turn ${firstError.turn}] ${truncate(firstError.text, 120)}`);
+      }
+    }
+  }
+
+  const totalLabelWidth = widths[0] + widths[1] + widths[2] + 4;
+  lines.push('─'.repeat(lines[0].length));
+
+  const totalCols: string[] = [pad('Total', totalLabelWidth)];
+  if (hasCost) totalCols.push(pad(formatCurrency(totalCost), widths[3], 'right'));
+  const tokenIdx = hasCost ? 4 : 3;
+  totalCols.push(pad(totalTokens > 0 ? totalTokens.toLocaleString('en-US') : '--', widths[tokenIdx], 'right'));
+  totalCols.push(pad(formatDuration(totalDurationMs), widths[tokenIdx + 1], 'right'));
+  totalCols.push(pad('', widths[tokenIdx + 2], 'right'));
+  lines.push(totalCols.join('  '));
+
+  return lines.map((line) => `  ${line}`).join('\n');
+}