@jmoyers/harness 0.1.0

package/src/services/startup-output-tracker.ts

@@ -0,0 +1,54 @@
+type PerfAttrs = Record<string, boolean | number | string>;
+
+interface StartupSequencerLike {
+  snapshot(): {
+    firstOutputObserved: boolean;
+  };
+  markFirstOutput(sessionId: string): boolean;
+}
+
+interface StartupSpanTrackerLike {
+  readonly firstPaintTargetSessionId: string | null;
+  endFirstOutputSpan(attrs: PerfAttrs): void;
+}
+
+interface StartupOutputTrackerOptions {
+  readonly startupSequencer: StartupSequencerLike;
+  readonly startupSpanTracker: StartupSpanTrackerLike;
+  readonly recordPerfEvent: (name: string, attrs: PerfAttrs) => void;
+}
+
+export class StartupOutputTracker {
+  private readonly sessionFirstOutputObserved = new Set<string>();
+
+  constructor(private readonly options: StartupOutputTrackerOptions) {}
+
+  onOutputChunk(sessionId: string, bytes: number): void {
+    if (!this.sessionFirstOutputObserved.has(sessionId)) {
+      this.sessionFirstOutputObserved.add(sessionId);
+      this.options.recordPerfEvent('mux.session.first-output', {
+        sessionId,
+        bytes,
+      });
+    }
+
+    const targetSessionId = this.options.startupSpanTracker.firstPaintTargetSessionId;
+    if (targetSessionId === null || sessionId !== targetSessionId) {
+      return;
+    }
+    if (this.options.startupSequencer.snapshot().firstOutputObserved) {
+      return;
+    }
+    if (!this.options.startupSequencer.markFirstOutput(sessionId)) {
+      return;
+    }
+    this.options.recordPerfEvent('mux.startup.active-first-output', {
+      sessionId,
+      bytes,
+    });
+    this.options.startupSpanTracker.endFirstOutputSpan({
+      observed: true,
+      bytes,
+    });
+  }
+}

package/src/services/startup-paint-tracker.ts

@@ -0,0 +1,115 @@
+import type { ConversationState } from '../mux/live-mux/conversation-state.ts';
+
+type PerfAttrs = Record<string, boolean | number | string>;
+
+interface StartupSequencerLike {
+  snapshot(): {
+    firstOutputObserved: boolean;
+    firstPaintObserved: boolean;
+  };
+  markFirstPaintVisible(sessionId: string, glyphCells: number): boolean;
+  markHeaderVisible(sessionId: string, visible: boolean): boolean;
+  maybeSelectSettleGate(sessionId: string, glyphCells: number): string | null;
+}
+
+interface StartupSpanTrackerLike {
+  readonly firstPaintTargetSessionId: string | null;
+  endFirstPaintSpan(attrs: PerfAttrs): void;
+}
+
+interface StartupVisibilityLike {
+  visibleGlyphCellCount(conversation: ConversationState): number;
+  codexHeaderVisible(conversation: ConversationState): boolean;
+}
+
+interface StartupSettledGateLike {
+  scheduleProbe(sessionId: string): void;
+}
+
+interface StartupPaintTrackerOptions {
+  readonly startupSequencer: StartupSequencerLike;
+  readonly startupSpanTracker: StartupSpanTrackerLike;
+  readonly startupVisibility: StartupVisibilityLike;
+  readonly startupSettledGate: StartupSettledGateLike;
+  readonly recordPerfEvent: (name: string, attrs: PerfAttrs) => void;
+}
+
+interface StartupRenderFlushInput {
+  readonly activeConversation: ConversationState | null;
+  readonly activeConversationId: string | null;
+  readonly rightFrameVisible: boolean;
+  readonly changedRowCount: number;
+}
+
+export class StartupPaintTracker {
+  constructor(private readonly options: StartupPaintTrackerOptions) {}
+
+  onRenderFlush(input: StartupRenderFlushInput): void {
+    const targetSessionId = this.options.startupSpanTracker.firstPaintTargetSessionId;
+    if (targetSessionId === null) {
+      return;
+    }
+    if (
+      input.activeConversation === null ||
+      !input.rightFrameVisible ||
+      input.activeConversationId !== targetSessionId
+    ) {
+      return;
+    }
+    const startupSnapshot = this.options.startupSequencer.snapshot();
+    if (!startupSnapshot.firstOutputObserved) {
+      return;
+    }
+
+    const glyphCells = this.options.startupVisibility.visibleGlyphCellCount(
+      input.activeConversation,
+    );
+    if (
+      !startupSnapshot.firstPaintObserved &&
+      this.options.startupSequencer.markFirstPaintVisible(targetSessionId, glyphCells)
+    ) {
+      this.options.recordPerfEvent('mux.startup.active-first-visible-paint', {
+        sessionId: targetSessionId,
+        changedRows: input.changedRowCount,
+        glyphCells,
+      });
+      this.options.startupSpanTracker.endFirstPaintSpan({
+        observed: true,
+        changedRows: input.changedRowCount,
+        glyphCells,
+      });
+    }
+
+    if (
+      this.options.startupSequencer.markHeaderVisible(
+        targetSessionId,
+        this.options.startupVisibility.codexHeaderVisible(input.activeConversation),
+      )
+    ) {
+      this.options.recordPerfEvent('mux.startup.active-header-visible', {
+        sessionId: targetSessionId,
+        glyphCells,
+      });
+    }
+    const selectedGate = this.options.startupSequencer.maybeSelectSettleGate(
+      targetSessionId,
+      glyphCells,
+    );
+    if (selectedGate !== null) {
+      this.options.recordPerfEvent('mux.startup.active-settle-gate', {
+        sessionId: targetSessionId,
+        gate: selectedGate,
+        glyphCells,
+      });
+    }
+    this.options.startupSettledGate.scheduleProbe(targetSessionId);
+  }
+
+  onOutputChunk(sessionId: string): void {
+    const targetSessionId = this.options.startupSpanTracker.firstPaintTargetSessionId;
+    if (targetSessionId === null || sessionId !== targetSessionId) {
+      return;
+    }
+    this.options.startupSettledGate.scheduleProbe(sessionId);
+  }
+}

package/src/services/startup-persisted-conversation-queue.ts

@@ -0,0 +1,45 @@
+export interface StartupQueueConversationRecord {
+  readonly live: boolean;
+}
+
+export interface StartupPersistedConversationQueueServiceOptions<
+  TConversation extends StartupQueueConversationRecord,
+> {
+  readonly orderedConversationIds: () => readonly string[];
+  readonly conversationById: (sessionId: string) => TConversation | undefined;
+  readonly queueBackgroundOp: (task: () => Promise<void>, label: string) => void;
+  readonly startConversation: (sessionId: string) => Promise<unknown>;
+  readonly markDirty: () => void;
+}
+
+export class StartupPersistedConversationQueueService<
+  TConversation extends StartupQueueConversationRecord,
+> {
+  constructor(
+    private readonly options: StartupPersistedConversationQueueServiceOptions<TConversation>,
+  ) {}
+
+  queuePersistedConversationsInBackground(activeSessionId: string | null): number {
+    const ordered = this.options.orderedConversationIds();
+    let queued = 0;
+    for (const sessionId of ordered) {
+      if (activeSessionId !== null && sessionId === activeSessionId) {
+        continue;
+      }
+      const conversation = this.options.conversationById(sessionId);
+      if (conversation === undefined || conversation.live) {
+        continue;
+      }
+      this.options.queueBackgroundOp(async () => {
+        const latest = this.options.conversationById(sessionId);
+        if (latest === undefined || latest.live) {
+          return;
+        }
+        await this.options.startConversation(sessionId);
+        this.options.markDirty();
+      }, `background-start:${sessionId}`);
+      queued += 1;
+    }
+    return queued;
+  }
+}

package/src/services/startup-settled-gate.ts

@@ -0,0 +1,67 @@
+import type { ConversationState } from '../mux/live-mux/conversation-state.ts';
+
+type PerfAttrs = Record<string, boolean | number | string>;
+
+interface StartupSettledProbeEvent {
+  readonly sessionId: string;
+  readonly gate: string;
+  readonly quietMs: number;
+}
+
+interface StartupSequencerLike {
+  clearSettledTimer(): void;
+  signalSettled(): void;
+  scheduleSettledProbe(
+    sessionId: string,
+    onSettled: (event: StartupSettledProbeEvent) => void,
+  ): void;
+}
+
+interface StartupSpanTrackerLike {
+  readonly firstPaintTargetSessionId: string | null;
+  endSettledSpan(attrs: PerfAttrs): void;
+}
+
+interface StartupSettledGateOptions {
+  readonly startupSequencer: StartupSequencerLike;
+  readonly startupSpanTracker: StartupSpanTrackerLike;
+  readonly getConversation: (sessionId: string) => ConversationState | undefined;
+  readonly visibleGlyphCellCount: (conversation: ConversationState) => number;
+  readonly recordPerfEvent: (name: string, attrs: PerfAttrs) => void;
+}
+
+export class StartupSettledGate {
+  constructor(private readonly options: StartupSettledGateOptions) {}
+
+  clearTimer(): void {
+    this.options.startupSequencer.clearSettledTimer();
+  }
+
+  signalSettled(): void {
+    this.options.startupSequencer.signalSettled();
+  }
+
+  scheduleProbe(sessionId: string): void {
+    this.options.startupSequencer.scheduleSettledProbe(sessionId, (event) => {
+      if (this.options.startupSpanTracker.firstPaintTargetSessionId !== event.sessionId) {
+        return;
+      }
+      const conversation = this.options.getConversation(event.sessionId);
+      const glyphCells =
+        conversation === undefined ? 0 : this.options.visibleGlyphCellCount(conversation);
+      this.options.recordPerfEvent('mux.startup.active-settled', {
+        sessionId: event.sessionId,
+        gate: event.gate,
+        quietMs: event.quietMs,
+        glyphCells,
+      });
+      this.options.startupSpanTracker.endSettledSpan({
+        observed: true,
+        gate: event.gate,
+        quietMs: event.quietMs,
+        glyphCells,
+      });
+      this.options.startupSequencer.signalSettled();
+    });
+  }
+}

package/src/services/startup-shutdown.ts

@@ -0,0 +1,53 @@
+type SpanAttrs = Record<string, boolean | number | string>;
+
+interface StartupSnapshotLike {
+  firstOutputObserved: boolean;
+  firstPaintObserved: boolean;
+  settledObserved: boolean;
+  settleGate: string | null;
+}
+
+interface StartupSequencerLike {
+  snapshot(): StartupSnapshotLike;
+}
+
+interface StartupSpanTrackerLike {
+  endStartCommandSpan(attrs: SpanAttrs): void;
+  endFirstOutputSpan(attrs: SpanAttrs): void;
+  endFirstPaintSpan(attrs: SpanAttrs): void;
+  endSettledSpan(attrs: SpanAttrs): void;
+}
+
+interface StartupSettledGateLike {
+  clearTimer(): void;
+  signalSettled(): void;
+}
+
+interface StartupShutdownServiceOptions {
+  readonly startupSequencer: StartupSequencerLike;
+  readonly startupSpanTracker: StartupSpanTrackerLike;
+  readonly startupSettledGate: StartupSettledGateLike;
+}
+
+export class StartupShutdownService {
+  constructor(private readonly options: StartupShutdownServiceOptions) {}
+
+  finalize(): void {
+    this.options.startupSpanTracker.endStartCommandSpan({
+      observed: false,
+    });
+    const startupSnapshot = this.options.startupSequencer.snapshot();
+    this.options.startupSpanTracker.endFirstOutputSpan({
+      observed: startupSnapshot.firstOutputObserved,
+    });
+    this.options.startupSpanTracker.endFirstPaintSpan({
+      observed: startupSnapshot.firstPaintObserved,
+    });
+    this.options.startupSettledGate.clearTimer();
+    this.options.startupSpanTracker.endSettledSpan({
+      observed: startupSnapshot.settledObserved,
+      gate: startupSnapshot.settleGate ?? 'none',
+    });
+    this.options.startupSettledGate.signalSettled();
+  }
+}

package/src/services/startup-span-tracker.ts

@@ -0,0 +1,77 @@
+type SpanAttributes = Record<string, boolean | number | string>;
+
+interface PerfSpanLike {
+  end(attrs: SpanAttributes): void;
+}
+
+type StartPerfSpanLike = (name: string, attrs: SpanAttributes) => PerfSpanLike;
+
+export class StartupSpanTracker {
+  private activeStartCommandSpan: PerfSpanLike | null = null;
+  private activeFirstOutputSpan: PerfSpanLike | null = null;
+  private activeFirstPaintSpan: PerfSpanLike | null = null;
+  private activeSettledSpan: PerfSpanLike | null = null;
+  private activeFirstPaintTargetSessionId: string | null = null;
+
+  constructor(
+    private readonly startPerfSpan: StartPerfSpanLike,
+    private readonly startupSettleQuietMs: number,
+  ) {}
+
+  get firstPaintTargetSessionId(): string | null {
+    return this.activeFirstPaintTargetSessionId;
+  }
+
+  beginForSession(sessionId: string): void {
+    this.activeFirstPaintTargetSessionId = sessionId;
+    this.activeStartCommandSpan = this.startPerfSpan('mux.startup.active-start-command', {
+      sessionId,
+    });
+    this.activeFirstOutputSpan = this.startPerfSpan('mux.startup.active-first-output', {
+      sessionId,
+    });
+    this.activeFirstPaintSpan = this.startPerfSpan('mux.startup.active-first-visible-paint', {
+      sessionId,
+    });
+    this.activeSettledSpan = this.startPerfSpan('mux.startup.active-settled', {
+      sessionId,
+      quietMs: this.startupSettleQuietMs,
+    });
+  }
+
+  clearTargetSession(): void {
+    this.activeFirstPaintTargetSessionId = null;
+  }
+
+  endStartCommandSpan(attrs: SpanAttributes): void {
+    if (this.activeStartCommandSpan === null) {
+      return;
+    }
+    this.activeStartCommandSpan.end(attrs);
+    this.activeStartCommandSpan = null;
+  }
+
+  endFirstOutputSpan(attrs: SpanAttributes): void {
+    if (this.activeFirstOutputSpan === null) {
+      return;
+    }
+    this.activeFirstOutputSpan.end(attrs);
+    this.activeFirstOutputSpan = null;
+  }
+
+  endFirstPaintSpan(attrs: SpanAttributes): void {
+    if (this.activeFirstPaintSpan === null) {
+      return;
+    }
+    this.activeFirstPaintSpan.end(attrs);
+    this.activeFirstPaintSpan = null;
+  }
+
+  endSettledSpan(attrs: SpanAttributes): void {
+    if (this.activeSettledSpan === null) {
+      return;
+    }
+    this.activeSettledSpan.end(attrs);
+    this.activeSettledSpan = null;
+  }
+}

package/src/services/startup-state-hydration.ts

@@ -0,0 +1,94 @@
+interface RepositoryRecordLike {
+  readonly repositoryId: string;
+}
+
+interface DirectoryGitStatusLike<TRepository, TSummary, TSnapshot> {
+  readonly directoryId: string;
+  readonly summary: TSummary;
+  readonly repositorySnapshot: TSnapshot;
+  readonly repositoryId: string | null;
+  readonly repository: TRepository | null;
+}
+
+interface StartupStateHydrationServiceOptions<
+  TRepository extends RepositoryRecordLike,
+  TSummary,
+  TSnapshot,
+  TDirectoryGitStatus extends DirectoryGitStatusLike<TRepository, TSummary, TSnapshot>,
+> {
+  readonly hydrateConversationList: () => Promise<void>;
+  readonly listRepositories: () => Promise<readonly TRepository[]>;
+  readonly clearRepositories: () => void;
+  readonly setRepository: (repositoryId: string, repository: TRepository) => void;
+  readonly syncRepositoryAssociationsWithDirectorySnapshots: () => void;
+  readonly gitHydrationEnabled: boolean;
+  readonly listDirectoryGitStatuses: () => Promise<readonly TDirectoryGitStatus[]>;
+  readonly setDirectoryGitSummary: (directoryId: string, summary: TSummary) => void;
+  readonly setDirectoryRepositorySnapshot: (directoryId: string, snapshot: TSnapshot) => void;
+  readonly setDirectoryRepositoryAssociation: (
+    directoryId: string,
+    repositoryId: string | null,
+  ) => void;
+  readonly hydrateTaskPlanningState: () => Promise<void>;
+  readonly subscribeTaskPlanningEvents: (afterCursor: number | null) => Promise<void>;
+  readonly ensureActiveConversationId: () => void;
+  readonly activeConversationId: () => string | null;
+  readonly selectLeftNavConversation: (sessionId: string) => void;
+  readonly enterHomePane: () => void;
+}
+
+export class StartupStateHydrationService<
+  TRepository extends RepositoryRecordLike,
+  TSummary,
+  TSnapshot,
+  TDirectoryGitStatus extends DirectoryGitStatusLike<TRepository, TSummary, TSnapshot>,
+> {
+  constructor(
+    private readonly options: StartupStateHydrationServiceOptions<
+      TRepository,
+      TSummary,
+      TSnapshot,
+      TDirectoryGitStatus
+    >,
+  ) {}
+
+  async hydrateRepositoryList(): Promise<void> {
+    const rows = await this.options.listRepositories();
+    this.options.clearRepositories();
+    for (const record of rows) {
+      this.options.setRepository(record.repositoryId, record);
+    }
+    this.options.syncRepositoryAssociationsWithDirectorySnapshots();
+  }
+
+  async hydrateDirectoryGitStatus(): Promise<void> {
+    if (!this.options.gitHydrationEnabled) {
+      return;
+    }
+    const rows = await this.options.listDirectoryGitStatuses();
+    for (const record of rows) {
+      this.options.setDirectoryGitSummary(record.directoryId, record.summary);
+      this.options.setDirectoryRepositorySnapshot(record.directoryId, record.repositorySnapshot);
+      this.options.setDirectoryRepositoryAssociation(record.directoryId, record.repositoryId);
+      if (record.repository !== null) {
+        this.options.setRepository(record.repository.repositoryId, record.repository);
+      }
+    }
+    this.options.syncRepositoryAssociationsWithDirectorySnapshots();
+  }
+
+  async hydrateStartupState(afterCursor: number | null): Promise<void> {
+    await this.options.hydrateConversationList();
+    await this.hydrateRepositoryList();
+    await this.options.hydrateTaskPlanningState();
+    await this.hydrateDirectoryGitStatus();
+    await this.options.subscribeTaskPlanningEvents(afterCursor);
+    this.options.ensureActiveConversationId();
+    const activeConversationId = this.options.activeConversationId();
+    if (activeConversationId !== null) {
+      this.options.selectLeftNavConversation(activeConversationId);
+      return;
+    }
+    this.options.enterHomePane();
+  }
+}

package/src/services/startup-visibility.ts

@@ -0,0 +1,35 @@
+import type { ConversationState } from '../mux/live-mux/conversation-state.ts';
+
+export class StartupVisibility {
+  constructor() {}
+
+  visibleGlyphCellCount(conversation: ConversationState): number {
+    const frame = conversation.oracle.snapshotWithoutHash();
+    let count = 0;
+    for (const line of frame.richLines) {
+      for (const cell of line.cells) {
+        if (!cell.continued && cell.glyph.trim().length > 0) {
+          count += 1;
+        }
+      }
+    }
+    return count;
+  }
+
+  codexHeaderVisible(conversation: ConversationState): boolean {
+    const frame = conversation.oracle.snapshotWithoutHash();
+    const rows: string[] = [];
+    for (const line of frame.richLines) {
+      let row = '';
+      for (const cell of line.cells) {
+        if (cell.continued) {
+          continue;
+        }
+        row += cell.glyph;
+      }
+      rows.push(row.trimEnd());
+    }
+    const text = rows.join('\n');
+    return text.includes('OpenAI Codex') && text.includes('model:') && text.includes('directory:');
+  }
+}

package/src/services/status-timeline-recorder.ts

@@ -0,0 +1,144 @@
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import {
+  parseActiveStatusTimelineState,
+  type ActiveStatusTimelineState,
+} from '../mux/live-mux/status-timeline-state.ts';
+
+export interface StatusTimelineLabels {
+  readonly repositoryId: string | null;
+  readonly repositoryName: string | null;
+  readonly projectId: string | null;
+  readonly projectPath: string | null;
+  readonly threadId: string | null;
+  readonly threadTitle: string | null;
+  readonly agentType: string | null;
+  readonly conversationId: string | null;
+}
+
+interface StatusTimelineRecordInput {
+  readonly direction: 'incoming' | 'outgoing';
+  readonly source: string;
+  readonly eventType: string;
+  readonly labels: StatusTimelineLabels;
+  readonly payload: unknown;
+  readonly dedupeKey?: string;
+  readonly dedupeValue?: string;
+}
+
+interface StatusTimelineRecorderOptions {
+  readonly statePath: string;
+  readonly nowMs?: () => number;
+  readonly nowIso?: () => string;
+  readonly refreshIntervalMs?: number;
+}
+
+const DEFAULT_REFRESH_INTERVAL_MS = 250;
+
+export class StatusTimelineRecorder {
+  private readonly nowMs: () => number;
+  private readonly nowIso: () => string;
+  private readonly refreshIntervalMs: number;
+  private nextRefreshAtMs = 0;
+  private activeState: ActiveStatusTimelineState | null = null;
+  private activeOutputPath: string | null = null;
+  private outputFd: number | null = null;
+  private readonly dedupeValueByKey = new Map<string, string>();
+
+  constructor(private readonly options: StatusTimelineRecorderOptions) {
+    this.nowMs = options.nowMs ?? Date.now;
+    this.nowIso = options.nowIso ?? (() => new Date().toISOString());
+    this.refreshIntervalMs = options.refreshIntervalMs ?? DEFAULT_REFRESH_INTERVAL_MS;
+  }
+
+  record(input: StatusTimelineRecordInput): void {
+    this.refreshIfDue();
+    if (this.outputFd === null || this.activeState === null) {
+      return;
+    }
+    if (
+      input.dedupeKey !== undefined &&
+      input.dedupeValue !== undefined &&
+      this.dedupeValueByKey.get(input.dedupeKey) === input.dedupeValue
+    ) {
+      return;
+    }
+    if (input.dedupeKey !== undefined && input.dedupeValue !== undefined) {
+      this.dedupeValueByKey.set(input.dedupeKey, input.dedupeValue);
+    }
+    const record = {
+      ts: this.nowIso(),
+      direction: input.direction,
+      source: input.source,
+      eventType: input.eventType,
+      labels: input.labels,
+      payload: input.payload,
+    };
+    try {
+      writeSync(this.outputFd, `${JSON.stringify(record)}\n`);
+    } catch {
+      this.deactivate();
+    }
+  }
+
+  close(): void {
+    this.deactivate();
+  }
+
+  private refreshIfDue(): void {
+    const now = this.nowMs();
+    if (now < this.nextRefreshAtMs) {
+      return;
+    }
+    this.nextRefreshAtMs = now + this.refreshIntervalMs;
+    const nextState = this.readState();
+    if (nextState === null) {
+      this.deactivate();
+      return;
+    }
+    const nextOutputPath = resolve(nextState.outputPath);
+    if (this.activeOutputPath === nextOutputPath && this.outputFd !== null) {
+      this.activeState = nextState;
+      return;
+    }
+    this.activate(nextState, nextOutputPath);
+  }
+
+  private activate(state: ActiveStatusTimelineState, outputPath: string): void {
+    this.deactivate();
+    try {
+      mkdirSync(dirname(outputPath), { recursive: true });
+      this.outputFd = openSync(outputPath, 'a');
+      this.activeOutputPath = outputPath;
+      this.activeState = state;
+    } catch {
+      this.deactivate();
+    }
+  }
+
+  private deactivate(): void {
+    if (this.outputFd !== null) {
+      try {
+        closeSync(this.outputFd);
+      } catch {
+        // Best-effort close only.
+      }
+    }
+    this.outputFd = null;
+    this.activeOutputPath = null;
+    this.activeState = null;
+    this.dedupeValueByKey.clear();
+  }
+
+  private readState(): ActiveStatusTimelineState | null {
+    if (!existsSync(this.options.statePath)) {
+      return null;
+    }
+    try {
+      const raw = JSON.parse(readFileSync(this.options.statePath, 'utf8')) as unknown;
+      return parseActiveStatusTimelineState(raw);
+    } catch {
+      return null;
+    }
+  }
+}