@jmoyers/harness 0.1.0

package/src/mux/ansi-integrity.ts

@@ -0,0 +1,103 @@
+type ScanResult =
+  | {
+      readonly valid: true;
+    }
+  | {
+      readonly valid: false;
+      readonly reason: string;
+    };
+
+function scanAnsiText(text: string): ScanResult {
+  let index = 0;
+  while (index < text.length) {
+    const code = text.codePointAt(index)!;
+    const char = String.fromCodePoint(code);
+    const width = code > 0xffff ? 2 : 1;
+    if (char !== '\u001b') {
+      index += width;
+      continue;
+    }
+
+    const next = text[index + 1];
+    if (next === undefined) {
+      return {
+        valid: false,
+        reason: 'dangling ESC at end of row',
+      };
+    }
+
+    if (next === '[') {
+      let csiIndex = index + 2;
+      let foundFinal = false;
+      while (csiIndex < text.length) {
+        const csiCode = text.codePointAt(csiIndex)!;
+        if (csiCode >= 0x40 && csiCode <= 0x7e) {
+          foundFinal = true;
+          csiIndex += 1;
+          break;
+        }
+        if (csiCode < 0x20 || csiCode > 0x3f) {
+          return {
+            valid: false,
+            reason: `invalid CSI byte 0x${csiCode.toString(16)}`,
+          };
+        }
+        csiIndex += 1;
+      }
+      if (!foundFinal) {
+        return {
+          valid: false,
+          reason: 'unterminated CSI sequence',
+        };
+      }
+      index = csiIndex;
+      continue;
+    }
+
+    if (next === ']') {
+      let oscIndex = index + 2;
+      let terminated = false;
+      while (oscIndex < text.length) {
+        const oscCode = text.codePointAt(oscIndex)!;
+        if (oscCode === 0x07) {
+          terminated = true;
+          oscIndex += 1;
+          break;
+        }
+        if (oscCode === 0x1b && text[oscIndex + 1] === '\\') {
+          terminated = true;
+          oscIndex += 2;
+          break;
+        }
+        oscIndex += oscCode > 0xffff ? 2 : 1;
+      }
+      if (!terminated) {
+        return {
+          valid: false,
+          reason: 'unterminated OSC sequence',
+        };
+      }
+      index = oscIndex;
+      continue;
+    }
+
+    // Two-byte escape sequence.
+    index += 2;
+  }
+
+  return {
+    valid: true,
+  };
+}
+
+export function findAnsiIntegrityIssues(rows: readonly string[]): readonly string[] {
+  const issues: string[] = [];
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
+    const row = rows[rowIndex] ?? '';
+    const result = scanAnsiText(row);
+    if (!result.valid) {
+      issues.push(`row ${String(rowIndex + 1)}: ${result.reason}`);
+    }
+  }
+  return issues;
+}

package/src/mux/control-plane-op-queue.ts

@@ -0,0 +1,212 @@
+export type ControlPlaneOpPriority = 'interactive' | 'background';
+
+interface QueuedControlPlaneOp {
+  readonly id: number;
+  readonly priority: ControlPlaneOpPriority;
+  readonly label: string;
+  readonly enqueuedAtMs: number;
+  readonly task: () => Promise<void>;
+}
+
+interface ControlPlaneOpQueueMetrics {
+  readonly interactiveQueued: number;
+  readonly backgroundQueued: number;
+  readonly running: boolean;
+}
+
+interface ControlPlaneOpQueueEvent {
+  readonly id: number;
+  readonly priority: ControlPlaneOpPriority;
+  readonly label: string;
+  readonly enqueuedAtMs: number;
+}
+
+interface ControlPlaneOpQueueStartEvent extends ControlPlaneOpQueueEvent {
+  readonly waitMs: number;
+}
+
+interface ControlPlaneOpQueueOptions {
+  readonly nowMs?: () => number;
+  readonly schedule?: (callback: () => void) => void;
+  readonly onEnqueued?: (
+    event: ControlPlaneOpQueueEvent,
+    metrics: ControlPlaneOpQueueMetrics,
+  ) => void;
+  readonly onStart?: (
+    event: ControlPlaneOpQueueStartEvent,
+    metrics: ControlPlaneOpQueueMetrics,
+  ) => void;
+  readonly onSuccess?: (
+    event: ControlPlaneOpQueueStartEvent,
+    metrics: ControlPlaneOpQueueMetrics,
+  ) => void;
+  readonly onError?: (
+    event: ControlPlaneOpQueueStartEvent,
+    metrics: ControlPlaneOpQueueMetrics,
+    error: unknown,
+  ) => void;
+  readonly onFatal?: (error: unknown) => void;
+}
+
+function defaultSchedule(callback: () => void): void {
+  setImmediate(callback);
+}
+
+export class ControlPlaneOpQueue {
+  private readonly nowMs: () => number;
+  private readonly schedule: (callback: () => void) => void;
+  private readonly onEnqueued: ControlPlaneOpQueueOptions['onEnqueued'];
+  private readonly onStart: ControlPlaneOpQueueOptions['onStart'];
+  private readonly onSuccess: ControlPlaneOpQueueOptions['onSuccess'];
+  private readonly onError: ControlPlaneOpQueueOptions['onError'];
+  private readonly onFatal: ControlPlaneOpQueueOptions['onFatal'];
+
+  private readonly interactiveQueue: QueuedControlPlaneOp[] = [];
+  private readonly backgroundQueue: QueuedControlPlaneOp[] = [];
+  private readonly drainWaiters: Array<() => void> = [];
+  private nextId = 1;
+  private running = false;
+  private pumpScheduled = false;
+
+  constructor(options: ControlPlaneOpQueueOptions = {}) {
+    this.nowMs = options.nowMs ?? Date.now;
+    this.schedule = options.schedule ?? defaultSchedule;
+    this.onEnqueued = options.onEnqueued;
+    this.onStart = options.onStart;
+    this.onSuccess = options.onSuccess;
+    this.onError = options.onError;
+    this.onFatal = options.onFatal;
+  }
+
+  enqueueInteractive(task: () => Promise<void>, label = 'interactive-op'): void {
+    this.enqueue(task, 'interactive', label);
+  }
+
+  enqueueBackground(task: () => Promise<void>, label = 'background-op'): void {
+    this.enqueue(task, 'background', label);
+  }
+
+  async waitForDrain(): Promise<void> {
+    if (!this.running && this.interactiveQueue.length === 0 && this.backgroundQueue.length === 0) {
+      return;
+    }
+    await new Promise<void>((resolve) => {
+      this.drainWaiters.push(resolve);
+    });
+  }
+
+  metrics(): {
+    readonly interactiveQueued: number;
+    readonly backgroundQueued: number;
+    readonly running: boolean;
+  } {
+    return this.metricsSnapshot();
+  }
+
+  private enqueue(
+    task: () => Promise<void>,
+    priority: ControlPlaneOpPriority,
+    label: string,
+  ): void {
+    const op: QueuedControlPlaneOp = {
+      id: this.nextId,
+      priority,
+      label,
+      enqueuedAtMs: this.nowMs(),
+      task,
+    };
+    this.nextId += 1;
+
+    if (priority === 'interactive') {
+      this.interactiveQueue.push(op);
+    } else {
+      this.backgroundQueue.push(op);
+    }
+
+    this.onEnqueued?.(
+      {
+        id: op.id,
+        priority: op.priority,
+        label: op.label,
+        enqueuedAtMs: op.enqueuedAtMs,
+      },
+      this.metricsSnapshot(),
+    );
+    this.schedulePump();
+  }
+
+  private metricsSnapshot(): ControlPlaneOpQueueMetrics {
+    return {
+      interactiveQueued: this.interactiveQueue.length,
+      backgroundQueued: this.backgroundQueue.length,
+      running: this.running,
+    };
+  }
+
+  private resolveDrainIfIdle(): void {
+    if (this.running || this.interactiveQueue.length > 0 || this.backgroundQueue.length > 0) {
+      return;
+    }
+    while (this.drainWaiters.length > 0) {
+      const resolve = this.drainWaiters.shift();
+      resolve?.();
+    }
+  }
+
+  private pickNext(): QueuedControlPlaneOp | null {
+    const interactive = this.interactiveQueue.shift();
+    if (interactive !== undefined) {
+      return interactive;
+    }
+    const background = this.backgroundQueue.shift();
+    return background ?? null;
+  }
+
+  private schedulePump(): void {
+    if (this.pumpScheduled) {
+      return;
+    }
+    this.pumpScheduled = true;
+    this.schedule(() => {
+      this.pumpScheduled = false;
+      void this.runQueue().catch((error: unknown) => {
+        this.onFatal?.(error);
+      });
+    });
+  }
+
+  private async runQueue(): Promise<void> {
+    if (this.running) {
+      return;
+    }
+    const next = this.pickNext();
+    if (next === null) {
+      this.resolveDrainIfIdle();
+      return;
+    }
+
+    this.running = true;
+    const waitMs = Math.max(0, this.nowMs() - next.enqueuedAtMs);
+    const startEvent: ControlPlaneOpQueueStartEvent = {
+      id: next.id,
+      priority: next.priority,
+      label: next.label,
+      enqueuedAtMs: next.enqueuedAtMs,
+      waitMs,
+    };
+
+    try {
+      this.onStart?.(startEvent, this.metricsSnapshot());
+      try {
+        await next.task();
+        this.onSuccess?.(startEvent, this.metricsSnapshot());
+      } catch (error: unknown) {
+        this.onError?.(startEvent, this.metricsSnapshot(), error);
+      }
+    } finally {
+      this.running = false;
+      this.resolveDrainIfIdle();
+      this.schedulePump();
+    }
+  }
+}

package/src/mux/conversation-rail.ts

@@ -0,0 +1,339 @@
+import type {
+  StreamSessionListSort,
+  StreamSessionRuntimeStatus,
+  StreamSessionStatusModel,
+} from '../control-plane/stream-protocol.ts';
+import { padOrTrimDisplay } from './dual-pane-core.ts';
+import {
+  createUiSurface,
+  DEFAULT_UI_STYLE,
+  drawUiText,
+  fillUiRow,
+  renderUiSurfaceAnsiRows,
+} from '../ui/surface.ts';
+import { paintUiRow } from '../ui/kit.ts';
+
+export interface ConversationRailSessionSummary {
+  readonly sessionId: string;
+  readonly status: StreamSessionRuntimeStatus;
+  readonly statusModel: StreamSessionStatusModel | null;
+  readonly attentionReason: string | null;
+  readonly live: boolean;
+  readonly startedAt: string;
+  readonly lastEventAt: string | null;
+}
+
+type ConversationRailOrder = StreamSessionListSort | 'input-order';
+
+interface ConversationRailRenderRow {
+  readonly kind: 'header' | 'session' | 'empty';
+  readonly text: string;
+  readonly session?: ConversationRailSessionSummary;
+  readonly active?: boolean;
+}
+
+export function compareIsoDesc(left: string | null, right: string | null): number {
+  if (left === right) {
+    return 0;
+  }
+  if (left === null) {
+    return 1;
+  }
+  if (right === null) {
+    return -1;
+  }
+  return right.localeCompare(left);
+}
+
+const STATUS_PRIORITY: Record<StreamSessionRuntimeStatus, number> = {
+  'needs-input': 0,
+  running: 1,
+  completed: 2,
+  exited: 3,
+};
+
+function statusPriority(status: StreamSessionRuntimeStatus): number {
+  return STATUS_PRIORITY[status];
+}
+
+export function sortConversationRailSessions(
+  sessions: readonly ConversationRailSessionSummary[],
+  sort: StreamSessionListSort = 'attention-first',
+): readonly ConversationRailSessionSummary[] {
+  const sorted = [...sessions];
+  if (sort === 'started-asc') {
+    sorted.sort(
+      (left, right) =>
+        left.startedAt.localeCompare(right.startedAt) ||
+        left.sessionId.localeCompare(right.sessionId),
+    );
+    return sorted;
+  }
+
+  if (sort === 'started-desc') {
+    sorted.sort(
+      (left, right) =>
+        right.startedAt.localeCompare(left.startedAt) ||
+        left.sessionId.localeCompare(right.sessionId),
+    );
+    return sorted;
+  }
+
+  sorted.sort(
+    (left, right) =>
+      statusPriority(left.status) - statusPriority(right.status) ||
+      compareIsoDesc(left.lastEventAt, right.lastEventAt) ||
+      right.startedAt.localeCompare(left.startedAt) ||
+      left.sessionId.localeCompare(right.sessionId),
+  );
+  return sorted;
+}
+
+function compactSessionId(sessionId: string): string {
+  if (sessionId.startsWith('conversation-')) {
+    const suffix = sessionId.slice('conversation-'.length);
+    if (suffix.length > 8) {
+      return suffix.slice(0, 8);
+    }
+    return suffix;
+  }
+  if (sessionId.length > 16) {
+    return `${sessionId.slice(0, 16)}…`;
+  }
+  return sessionId;
+}
+
+function statusToken(status: StreamSessionRuntimeStatus): string {
+  if (status === 'needs-input') {
+    return '!';
+  }
+  if (status === 'running') {
+    return '~';
+  }
+  if (status === 'completed') {
+    return '+';
+  }
+  return 'x';
+}
+
+function renderConversationLine(
+  session: ConversationRailSessionSummary,
+  activeSessionId: string | null,
+): string {
+  const activePrefix = session.sessionId === activeSessionId ? '>' : ' ';
+  const token = statusToken(session.status);
+  const shortId = compactSessionId(session.sessionId);
+  const liveState = session.live ? '' : ' (dead)';
+  const base = `${activePrefix} [${token}] ${shortId}${liveState}`;
+  if (session.attentionReason !== null && session.attentionReason.length > 0) {
+    return `${base} - ${session.attentionReason}`;
+  }
+  return base;
+}
+
+function buildConversationRailRows(
+  sessions: readonly ConversationRailSessionSummary[],
+  activeSessionId: string | null,
+  maxRows: number,
+  order: ConversationRailOrder,
+): readonly ConversationRailRenderRow[] {
+  const safeMaxRows = Math.max(1, maxRows);
+  const sorted =
+    order === 'input-order' ? [...sessions] : sortConversationRailSessions(sessions, order);
+  const headerText = `conversations (${String(sorted.length)}) [ctrl-t new] [ctrl-n/p switch]`;
+  const rows: ConversationRailRenderRow[] = [
+    {
+      kind: 'header',
+      text: headerText,
+    },
+  ];
+
+  if (safeMaxRows === 1) {
+    return rows;
+  }
+
+  const maxConversationRows = safeMaxRows - 1;
+  const visible: ConversationRailSessionSummary[] = sorted.slice(0, maxConversationRows);
+  if (
+    activeSessionId !== null &&
+    !visible.some((session) => session.sessionId === activeSessionId)
+  ) {
+    const active = sorted.find((session) => session.sessionId === activeSessionId);
+    if (active !== undefined) {
+      visible[visible.length - 1] = active;
+    }
+  }
+
+  for (const session of visible) {
+    rows.push({
+      kind: 'session',
+      text: renderConversationLine(session, activeSessionId),
+      session,
+      active: session.sessionId === activeSessionId,
+    });
+  }
+
+  while (rows.length < safeMaxRows) {
+    rows.push({
+      kind: 'empty',
+      text: '',
+    });
+  }
+  return rows;
+}
+
+export function buildConversationRailLines(
+  sessions: readonly ConversationRailSessionSummary[],
+  activeSessionId: string | null,
+  width: number,
+  maxRows: number,
+  order: ConversationRailOrder = 'attention-first',
+): readonly string[] {
+  const safeWidth = Math.max(1, width);
+  const rows = buildConversationRailRows(sessions, activeSessionId, maxRows, order);
+  return rows.map((row) => padOrTrimDisplay(row.text, safeWidth));
+}
+
+const HEADER_ROW_STYLE = {
+  fg: { kind: 'indexed', index: 250 } as const,
+  bg: { kind: 'indexed', index: 236 } as const,
+  bold: false,
+};
+const NORMAL_ROW_STYLE = DEFAULT_UI_STYLE;
+const ACTIVE_ROW_STYLE = {
+  fg: { kind: 'indexed', index: 255 } as const,
+  bg: { kind: 'indexed', index: 238 } as const,
+  bold: false,
+};
+const ACTIVE_INDICATOR_STYLE = {
+  fg: { kind: 'indexed', index: 231 } as const,
+  bg: { kind: 'indexed', index: 238 } as const,
+  bold: true,
+};
+const BADGE_STYLES = {
+  'needs-input': {
+    fg: { kind: 'indexed', index: 231 } as const,
+    bg: { kind: 'indexed', index: 166 } as const,
+    bold: true,
+  },
+  running: {
+    fg: { kind: 'indexed', index: 231 } as const,
+    bg: { kind: 'indexed', index: 24 } as const,
+    bold: true,
+  },
+  completed: {
+    fg: { kind: 'indexed', index: 231 } as const,
+    bg: { kind: 'indexed', index: 28 } as const,
+    bold: true,
+  },
+  exited: {
+    fg: { kind: 'indexed', index: 250 } as const,
+    bg: { kind: 'indexed', index: 239 } as const,
+    bold: true,
+  },
+} as const;
+const ACTIVE_TEXT_STYLE = {
+  fg: { kind: 'indexed', index: 255 } as const,
+  bg: { kind: 'indexed', index: 238 } as const,
+  bold: false,
+};
+const NORMAL_TEXT_STYLE = DEFAULT_UI_STYLE;
+const MUTED_TEXT_STYLE = {
+  fg: { kind: 'indexed', index: 245 } as const,
+  bg: { kind: 'default' } as const,
+  bold: false,
+};
+
+function badgeLabel(status: StreamSessionRuntimeStatus): string {
+  if (status === 'needs-input') {
+    return 'NEED';
+  }
+  if (status === 'running') {
+    return 'RUN ';
+  }
+  if (status === 'completed') {
+    return 'DONE';
+  }
+  return 'EXIT';
+}
+
+function rowBodyText(session: ConversationRailSessionSummary): string {
+  const idText = compactSessionId(session.sessionId);
+  const deadToken = session.live ? '' : ' (dead)';
+  const attentionText =
+    session.attentionReason !== null && session.attentionReason.length > 0
+      ? ` - ${session.attentionReason}`
+      : '';
+  return `${idText}${deadToken}${attentionText}`;
+}
+
+export function renderConversationRailAnsiRows(
+  sessions: readonly ConversationRailSessionSummary[],
+  activeSessionId: string | null,
+  width: number,
+  maxRows: number,
+  order: ConversationRailOrder = 'attention-first',
+): readonly string[] {
+  const safeWidth = Math.max(1, width);
+  const rows = buildConversationRailRows(sessions, activeSessionId, maxRows, order);
+  const surface = createUiSurface(safeWidth, rows.length, DEFAULT_UI_STYLE);
+
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
+    const row = rows[rowIndex]!;
+    if (row.kind === 'header') {
+      paintUiRow(surface, rowIndex, row.text, HEADER_ROW_STYLE, HEADER_ROW_STYLE, 1);
+      continue;
+    }
+
+    if (row.kind === 'empty') {
+      paintUiRow(surface, rowIndex, '', NORMAL_ROW_STYLE, NORMAL_ROW_STYLE);
+      continue;
+    }
+
+    const session = row.session!;
+    const active = row.active === true;
+    fillUiRow(surface, rowIndex, active ? ACTIVE_ROW_STYLE : NORMAL_ROW_STYLE);
+    drawUiText(
+      surface,
+      0,
+      rowIndex,
+      active ? '>' : ' ',
+      active ? ACTIVE_INDICATOR_STYLE : NORMAL_TEXT_STYLE,
+    );
+    drawUiText(surface, 2, rowIndex, badgeLabel(session.status), BADGE_STYLES[session.status]);
+    drawUiText(
+      surface,
+      7,
+      rowIndex,
+      rowBodyText(session),
+      active ? ACTIVE_TEXT_STYLE : NORMAL_TEXT_STYLE,
+    );
+
+    if (!session.live && session.attentionReason === null) {
+      drawUiText(surface, 7, rowIndex, rowBodyText(session), MUTED_TEXT_STYLE);
+    }
+  }
+
+  return renderUiSurfaceAnsiRows(surface);
+}
+
+export function cycleConversationId(
+  sessionIds: readonly string[],
+  activeSessionId: string | null,
+  direction: 'next' | 'previous',
+): string | null {
+  if (sessionIds.length === 0) {
+    return null;
+  }
+  if (activeSessionId === null) {
+    return sessionIds[0]!;
+  }
+  const index = sessionIds.indexOf(activeSessionId);
+  if (index < 0) {
+    return sessionIds[0]!;
+  }
+  if (direction === 'next') {
+    return sessionIds[(index + 1) % sessionIds.length]!;
+  }
+  return sessionIds[(index - 1 + sessionIds.length) % sessionIds.length]!;
+}