@jmoyers/harness 0.1.0

package/src/mux/runtime-wiring.ts

@@ -0,0 +1,185 @@
+import type { ControlPlaneKeyEvent } from '../control-plane/codex-session-stream.ts';
+import type {
+  StreamSessionController,
+  StreamSessionRuntimeStatus,
+  StreamSessionStatusModel,
+} from '../control-plane/stream-protocol.ts';
+
+export interface MuxRuntimeConversationState {
+  directoryId: string | null;
+  status: StreamSessionRuntimeStatus;
+  statusModel: StreamSessionStatusModel | null;
+  attentionReason: string | null;
+  live: boolean;
+  controller: StreamSessionController | null;
+  lastEventAt: string | null;
+  lastKnownWork: string | null;
+  lastKnownWorkAt: string | null;
+  lastTelemetrySource: string | null;
+}
+
+interface EnsureConversationSeed {
+  directoryId?: string | null;
+}
+
+interface ApplyMuxControlPlaneKeyEventOptions<TConversation extends MuxRuntimeConversationState> {
+  readonly removedConversationIds: ReadonlySet<string>;
+  ensureConversation: (sessionId: string, seed?: EnsureConversationSeed) => TConversation;
+}
+
+interface MuxTelemetrySummaryInput {
+  readonly source: string;
+  readonly eventName: string | null;
+  readonly summary: string | null;
+  readonly observedAt: string;
+}
+
+interface ProjectedTelemetrySummary {
+  readonly text: string | null;
+}
+
+function parseIsoMs(value: string | null): number {
+  if (value === null) {
+    return Number.NaN;
+  }
+  return Date.parse(value);
+}
+
+function normalizeEventName(value: string | null): string {
+  return (value ?? '').trim().toLowerCase();
+}
+
+function normalizeSummary(value: string | null): string {
+  return (value ?? '').trim();
+}
+
+function projectTelemetrySummary(
+  telemetry: Omit<MuxTelemetrySummaryInput, 'observedAt'>,
+): ProjectedTelemetrySummary {
+  const eventName = normalizeEventName(telemetry.eventName);
+  const summary = normalizeSummary(telemetry.summary);
+  const summaryLower = summary.toLowerCase();
+  if (telemetry.source === 'otlp-metric') {
+    if (eventName === 'codex.turn.e2e_duration_ms') {
+      return {
+        text: 'inactive',
+      };
+    }
+    return {
+      text: null,
+    };
+  }
+  if (telemetry.source === 'otlp-log' && eventName === 'codex.sse_event') {
+    if (
+      summaryLower.includes('response.created') ||
+      summaryLower.includes('response.in_progress') ||
+      summaryLower.includes('response.output_text.delta') ||
+      summaryLower.includes('response.output_item.added') ||
+      summaryLower.includes('response.function_call_arguments.delta')
+    ) {
+      return {
+        text: 'active',
+      };
+    }
+  }
+  if (eventName === 'codex.user_prompt') {
+    return {
+      text: 'active',
+    };
+  }
+  if (eventName === 'claude.userpromptsubmit' || eventName === 'claude.pretooluse') {
+    return {
+      text: 'active',
+    };
+  }
+  if (
+    eventName === 'claude.stop' ||
+    eventName === 'claude.subagentstop' ||
+    eventName === 'claude.sessionend'
+  ) {
+    return {
+      text: 'inactive',
+    };
+  }
+  if (
+    eventName === 'cursor.beforesubmitprompt' ||
+    eventName === 'cursor.beforeshellexecution' ||
+    eventName === 'cursor.beforemcptool'
+  ) {
+    return {
+      text: 'active',
+    };
+  }
+  if (eventName === 'cursor.stop' || eventName === 'cursor.sessionend') {
+    return {
+      text: 'inactive',
+    };
+  }
+  return {
+    text: null,
+  };
+}
+
+export function telemetrySummaryText(
+  summary: Omit<MuxTelemetrySummaryInput, 'observedAt'>,
+): string | null {
+  const projected = projectTelemetrySummary(summary);
+  return projected.text;
+}
+
+export function applyTelemetrySummaryToConversation<
+  TConversation extends MuxRuntimeConversationState,
+>(target: TConversation, telemetry: MuxTelemetrySummaryInput | null): void {
+  if (telemetry === null) {
+    return;
+  }
+  const observedAtMs = parseIsoMs(telemetry.observedAt);
+  const currentAtMs = parseIsoMs(target.lastKnownWorkAt);
+  if (Number.isFinite(currentAtMs) && Number.isFinite(observedAtMs) && observedAtMs < currentAtMs) {
+    return;
+  }
+  const projected = projectTelemetrySummary(telemetry);
+  if (projected.text !== null) {
+    target.lastKnownWork = projected.text;
+    target.lastKnownWorkAt = telemetry.observedAt;
+    target.lastTelemetrySource = telemetry.source;
+  }
+}
+
+export function applyMuxControlPlaneKeyEvent<TConversation extends MuxRuntimeConversationState>(
+  event: ControlPlaneKeyEvent,
+  options: ApplyMuxControlPlaneKeyEventOptions<TConversation>,
+): TConversation | null {
+  if (options.removedConversationIds.has(event.sessionId)) {
+    return null;
+  }
+  const conversation = options.ensureConversation(event.sessionId, {
+    directoryId: event.directoryId,
+  });
+  if (event.directoryId !== null) {
+    conversation.directoryId = event.directoryId;
+  }
+
+  if (event.type === 'session-status') {
+    conversation.status = event.status;
+    conversation.statusModel = event.statusModel;
+    conversation.attentionReason = event.attentionReason;
+    conversation.live = event.live;
+    conversation.controller = event.controller;
+    conversation.lastEventAt = event.ts;
+    conversation.lastKnownWork = event.statusModel?.lastKnownWork ?? null;
+    conversation.lastKnownWorkAt = event.statusModel?.lastKnownWorkAt ?? null;
+    conversation.lastTelemetrySource = event.telemetry?.source ?? null;
+    return conversation;
+  }
+
+  if (event.type === 'session-control') {
+    conversation.controller = event.controller;
+    conversation.lastEventAt = event.ts;
+    return conversation;
+  }
+
+  conversation.lastEventAt = event.keyEvent.observedAt;
+  conversation.lastTelemetrySource = event.keyEvent.source;
+  return conversation;
+}

package/src/mux/selector-index.ts

@@ -0,0 +1,160 @@
+interface SelectorIndexDirectory {
+  readonly directoryId: string;
+}
+
+interface SelectorIndexConversation {
+  readonly sessionId: string;
+  readonly directoryId: string | null;
+  readonly title: string;
+  readonly agentType: string;
+}
+
+interface SelectorIndexEntry {
+  readonly selectorIndex: number;
+  readonly directoryIndex: number;
+  readonly directoryId: string;
+  readonly sessionId: string;
+  readonly title: string;
+  readonly agentType: string;
+}
+
+type LeftNavSelectorEntry =
+  | {
+      readonly selectorIndex: number;
+      readonly key: 'home';
+      readonly kind: 'home';
+    }
+  | {
+      readonly selectorIndex: number;
+      readonly key: `directory:${string}`;
+      readonly kind: 'directory';
+      readonly directoryId: string;
+    }
+  | {
+      readonly selectorIndex: number;
+      readonly key: `conversation:${string}`;
+      readonly kind: 'conversation';
+      readonly directoryId: string;
+      readonly sessionId: string;
+    };
+
+function normalizedDirectoryId(directoryId: string | null): string {
+  if (directoryId === null) {
+    return 'directory-missing';
+  }
+  const trimmed = directoryId.trim();
+  return trimmed.length === 0 ? 'directory-missing' : trimmed;
+}
+
+function orderedDirectoryIds(
+  directories: ReadonlyMap<string, SelectorIndexDirectory>,
+  conversationById: ReadonlyMap<string, SelectorIndexConversation>,
+  orderedSessionIds: readonly string[],
+): readonly string[] {
+  const orderedDirectoryIds: string[] = [...directories.keys()];
+  const seenDirectoryIds = new Set(orderedDirectoryIds);
+
+  for (const sessionId of orderedSessionIds) {
+    const conversation = conversationById.get(sessionId);
+    if (conversation === undefined) {
+      continue;
+    }
+    const directoryId = normalizedDirectoryId(conversation.directoryId);
+    if (seenDirectoryIds.has(directoryId)) {
+      continue;
+    }
+    seenDirectoryIds.add(directoryId);
+    orderedDirectoryIds.push(directoryId);
+  }
+
+  return orderedDirectoryIds;
+}
+
+export function buildSelectorIndexEntries(
+  directories: ReadonlyMap<string, SelectorIndexDirectory>,
+  conversationById: ReadonlyMap<string, SelectorIndexConversation>,
+  orderedSessionIds: readonly string[],
+): readonly SelectorIndexEntry[] {
+  const entries: SelectorIndexEntry[] = [];
+  let selectorIndex = 1;
+  for (const directoryId of orderedDirectoryIds(directories, conversationById, orderedSessionIds)) {
+    let directoryIndex = 0;
+    for (const sessionId of orderedSessionIds) {
+      const conversation = conversationById.get(sessionId);
+      if (conversation === undefined) {
+        continue;
+      }
+      if (normalizedDirectoryId(conversation.directoryId) !== directoryId) {
+        continue;
+      }
+      directoryIndex += 1;
+      entries.push({
+        selectorIndex,
+        directoryIndex,
+        directoryId,
+        sessionId: conversation.sessionId,
+        title: conversation.title,
+        agentType: conversation.agentType,
+      });
+      selectorIndex += 1;
+    }
+  }
+  return entries;
+}
+
+export function visualConversationOrder(
+  directories: ReadonlyMap<string, SelectorIndexDirectory>,
+  conversationById: ReadonlyMap<string, SelectorIndexConversation>,
+  orderedSessionIds: readonly string[],
+): readonly string[] {
+  return buildSelectorIndexEntries(directories, conversationById, orderedSessionIds).map(
+    (entry) => entry.sessionId,
+  );
+}
+
+export function buildLeftNavSelectorEntries(
+  directories: ReadonlyMap<string, SelectorIndexDirectory>,
+  conversationById: ReadonlyMap<string, SelectorIndexConversation>,
+  orderedSessionIds: readonly string[],
+  options: {
+    readonly includeHome?: boolean;
+  } = {},
+): readonly LeftNavSelectorEntry[] {
+  const entries: LeftNavSelectorEntry[] = [];
+  let selectorIndex = 1;
+  if (options.includeHome ?? false) {
+    entries.push({
+      selectorIndex,
+      key: 'home',
+      kind: 'home',
+    });
+    selectorIndex += 1;
+  }
+  for (const directoryId of orderedDirectoryIds(directories, conversationById, orderedSessionIds)) {
+    entries.push({
+      selectorIndex,
+      key: `directory:${directoryId}`,
+      kind: 'directory',
+      directoryId,
+    });
+    selectorIndex += 1;
+    for (const sessionId of orderedSessionIds) {
+      const conversation = conversationById.get(sessionId);
+      if (conversation === undefined) {
+        continue;
+      }
+      if (normalizedDirectoryId(conversation.directoryId) !== directoryId) {
+        continue;
+      }
+      entries.push({
+        selectorIndex,
+        key: `conversation:${conversation.sessionId}`,
+        kind: 'conversation',
+        directoryId,
+        sessionId: conversation.sessionId,
+      });
+      selectorIndex += 1;
+    }
+  }
+  return entries;
+}

package/src/mux/startup-sequencer.ts

@@ -0,0 +1,238 @@
+type StartupSettleGate = 'header' | 'nonempty';
+
+type StartupSequencerPhase =
+  | 'inactive'
+  | 'waiting-for-output'
+  | 'waiting-for-paint'
+  | 'waiting-for-header'
+  | 'settling'
+  | 'settled';
+
+interface StartupSequencerOptions {
+  readonly quietMs: number;
+  readonly nonemptyFallbackMs: number;
+  readonly nowMs?: () => number;
+  readonly setTimer?: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
+  readonly clearTimer?: (handle: ReturnType<typeof setTimeout>) => void;
+}
+
+interface StartupSequencerSnapshot {
+  readonly targetSessionId: string | null;
+  readonly phase: StartupSequencerPhase;
+  readonly firstOutputObserved: boolean;
+  readonly firstOutputAtMs: number | null;
+  readonly firstPaintObserved: boolean;
+  readonly headerObserved: boolean;
+  readonly settleGate: StartupSettleGate | null;
+  readonly settledObserved: boolean;
+  readonly settledSignaled: boolean;
+}
+
+interface StartupSettledEvent {
+  readonly sessionId: string;
+  readonly gate: StartupSettleGate;
+  readonly quietMs: number;
+}
+
+function defaultSetTimer(callback: () => void, delayMs: number): ReturnType<typeof setTimeout> {
+  return setTimeout(callback, delayMs);
+}
+
+function defaultClearTimer(handle: ReturnType<typeof setTimeout>): void {
+  clearTimeout(handle);
+}
+
+export class StartupSequencer {
+  private readonly quietMs: number;
+  private readonly nonemptyFallbackMs: number;
+  private readonly nowMs: () => number;
+  private readonly setTimer: (
+    callback: () => void,
+    delayMs: number,
+  ) => ReturnType<typeof setTimeout>;
+  private readonly clearTimer: (handle: ReturnType<typeof setTimeout>) => void;
+
+  private targetSessionId: string | null = null;
+  private phase: StartupSequencerPhase = 'inactive';
+  private firstOutputObserved = false;
+  private firstOutputAtMs: number | null = null;
+  private firstPaintObserved = false;
+  private headerObserved = false;
+  private settleGate: StartupSettleGate | null = null;
+  private settledObserved = false;
+  private settledSignaled = false;
+  private settledTimer: ReturnType<typeof setTimeout> | null = null;
+  private settledWait: Promise<void>;
+  private resolveSettledWait: (() => void) | null = null;
+
+  constructor(options: StartupSequencerOptions) {
+    this.quietMs = Math.max(0, Math.floor(options.quietMs));
+    this.nonemptyFallbackMs = Math.max(0, Math.floor(options.nonemptyFallbackMs));
+    this.nowMs = options.nowMs ?? Date.now;
+    this.setTimer = options.setTimer ?? defaultSetTimer;
+    this.clearTimer = options.clearTimer ?? defaultClearTimer;
+    this.settledWait = this.createSettledWait();
+  }
+
+  waitForSettled(): Promise<void> {
+    return this.settledWait;
+  }
+
+  setTargetSession(sessionId: string | null): void {
+    this.clearSettledTimer();
+    this.targetSessionId = sessionId;
+    this.phase = sessionId === null ? 'inactive' : 'waiting-for-output';
+    this.firstOutputObserved = false;
+    this.firstOutputAtMs = null;
+    this.firstPaintObserved = false;
+    this.headerObserved = false;
+    this.settleGate = null;
+    this.settledObserved = false;
+    this.settledSignaled = false;
+    this.settledWait = this.createSettledWait();
+  }
+
+  snapshot(): StartupSequencerSnapshot {
+    return {
+      targetSessionId: this.targetSessionId,
+      phase: this.phase,
+      firstOutputObserved: this.firstOutputObserved,
+      firstOutputAtMs: this.firstOutputAtMs,
+      firstPaintObserved: this.firstPaintObserved,
+      headerObserved: this.headerObserved,
+      settleGate: this.settleGate,
+      settledObserved: this.settledObserved,
+      settledSignaled: this.settledSignaled,
+    };
+  }
+
+  markFirstOutput(sessionId: string): boolean {
+    if (!this.hasTargetSession(sessionId) || this.firstOutputObserved) {
+      return false;
+    }
+    this.firstOutputObserved = true;
+    this.firstOutputAtMs = this.nowMs();
+    if (!this.settledObserved) {
+      this.phase = 'waiting-for-paint';
+    }
+    return true;
+  }
+
+  markFirstPaintVisible(sessionId: string, glyphCells: number): boolean {
+    if (
+      !this.hasTargetSession(sessionId) ||
+      this.firstPaintObserved ||
+      !this.firstOutputObserved ||
+      glyphCells <= 0
+    ) {
+      return false;
+    }
+    this.firstPaintObserved = true;
+    if (!this.settledObserved) {
+      this.phase = 'waiting-for-header';
+    }
+    return true;
+  }
+
+  markHeaderVisible(sessionId: string, visible: boolean): boolean {
+    if (!this.hasTargetSession(sessionId) || !visible || this.headerObserved) {
+      return false;
+    }
+    this.headerObserved = true;
+    return true;
+  }
+
+  maybeSelectSettleGate(sessionId: string, glyphCells: number): StartupSettleGate | null {
+    if (!this.hasTargetSession(sessionId) || this.settleGate !== null) {
+      return null;
+    }
+    if (this.headerObserved) {
+      this.settleGate = 'header';
+    } else if (
+      glyphCells > 0 &&
+      this.firstOutputAtMs !== null &&
+      this.nowMs() - this.firstOutputAtMs >= this.nonemptyFallbackMs
+    ) {
+      this.settleGate = 'nonempty';
+    }
+    if (this.settleGate !== null && !this.settledObserved) {
+      this.phase = 'settling';
+    }
+    return this.settleGate;
+  }
+
+  scheduleSettledProbe(
+    sessionId: string,
+    onSettled: (event: StartupSettledEvent) => void,
+  ): boolean {
+    if (
+      !this.hasTargetSession(sessionId) ||
+      !this.firstOutputObserved ||
+      !this.firstPaintObserved ||
+      this.settleGate === null ||
+      this.settledObserved
+    ) {
+      return false;
+    }
+    if (this.settleGate === 'header') {
+      if (this.settledTimer !== null) {
+        return false;
+      }
+    } else {
+      this.clearSettledTimer();
+    }
+
+    this.settledTimer = this.setTimer(() => {
+      this.settledTimer = null;
+      if (!this.hasTargetSession(sessionId) || this.settledObserved || this.settleGate === null) {
+        return;
+      }
+      this.settledObserved = true;
+      this.phase = 'settled';
+      onSettled({
+        sessionId,
+        gate: this.settleGate,
+        quietMs: this.quietMs,
+      });
+      this.signalSettled();
+    }, this.quietMs);
+    return true;
+  }
+
+  clearSettledTimer(): boolean {
+    if (this.settledTimer === null) {
+      return false;
+    }
+    this.clearTimer(this.settledTimer);
+    this.settledTimer = null;
+    return true;
+  }
+
+  signalSettled(): boolean {
+    if (this.settledSignaled) {
+      return false;
+    }
+    this.settledSignaled = true;
+    this.resolveSettledWait?.();
+    this.resolveSettledWait = null;
+    return true;
+  }
+
+  finalize(): void {
+    this.clearSettledTimer();
+    this.signalSettled();
+  }
+
+  private hasTargetSession(sessionId: string): boolean {
+    return this.targetSessionId !== null && this.targetSessionId === sessionId;
+  }
+
+  private createSettledWait(): Promise<void> {
+    let resolveFn: (() => void) | null = null;
+    const wait = new Promise<void>((resolve) => {
+      resolveFn = resolve;
+    });
+    this.resolveSettledWait = resolveFn;
+    return wait;
+  }
+}