@jmoyers/harness 0.1.0

package/src/services/process-usage-refresh.ts

@@ -0,0 +1,88 @@
+import { refreshProcessUsageSnapshots } from '../mux/live-mux/process-usage.ts';
+
+type PerfAttrs = Record<string, boolean | number | string>;
+
+interface PerfSpanLike {
+  end(attrs: PerfAttrs): void;
+}
+
+type StartPerfSpanLike = (name: string, attrs: PerfAttrs) => PerfSpanLike;
+
+interface RefreshProcessUsageSnapshotsResult {
+  readonly samples: number;
+  readonly changed: boolean;
+}
+
+interface RefreshProcessUsageSnapshotsFn<TConversation, TSample> {
+  (options: {
+    conversations: ReadonlyMap<string, TConversation>;
+    processUsageBySessionId: Map<string, TSample>;
+    readProcessUsageSample: (processId: number | null) => Promise<TSample>;
+    processIdForConversation: (conversation: TConversation) => number | null;
+    processUsageEqual: (left: TSample, right: TSample) => boolean;
+  }): Promise<RefreshProcessUsageSnapshotsResult>;
+}
+
+interface ProcessUsageRefreshServiceOptions<TConversation, TSample> {
+  readonly readProcessUsageSample: (processId: number | null) => Promise<TSample>;
+  readonly processIdForConversation: (conversation: TConversation) => number | null;
+  readonly processUsageEqual: (left: TSample, right: TSample) => boolean;
+  readonly startPerfSpan: StartPerfSpanLike;
+  readonly onChanged: () => void;
+  readonly refreshSnapshots?: RefreshProcessUsageSnapshotsFn<TConversation, TSample>;
+}
+
+export class ProcessUsageRefreshService<TConversation, TSample> {
+  private readonly processUsageBySessionId = new Map<string, TSample>();
+  private refreshInFlight = false;
+  private readonly refreshSnapshots: RefreshProcessUsageSnapshotsFn<TConversation, TSample>;
+
+  constructor(private readonly options: ProcessUsageRefreshServiceOptions<TConversation, TSample>) {
+    this.refreshSnapshots = options.refreshSnapshots ?? refreshProcessUsageSnapshots;
+  }
+
+  getSample(sessionId: string): TSample | undefined {
+    return this.processUsageBySessionId.get(sessionId);
+  }
+
+  deleteSession(sessionId: string): void {
+    this.processUsageBySessionId.delete(sessionId);
+  }
+
+  readonlyUsage(): ReadonlyMap<string, TSample> {
+    return this.processUsageBySessionId;
+  }
+
+  async refresh(
+    reason: 'startup' | 'interval',
+    conversations: ReadonlyMap<string, TConversation>,
+  ): Promise<void> {
+    if (this.refreshInFlight) {
+      return;
+    }
+    this.refreshInFlight = true;
+    const usageSpan = this.options.startPerfSpan('mux.background.process-usage', {
+      reason,
+      conversations: conversations.size,
+    });
+    try {
+      const refreshed = await this.refreshSnapshots({
+        conversations,
+        processUsageBySessionId: this.processUsageBySessionId,
+        readProcessUsageSample: this.options.readProcessUsageSample,
+        processIdForConversation: this.options.processIdForConversation,
+        processUsageEqual: this.options.processUsageEqual,
+      });
+      if (refreshed.changed) {
+        this.options.onChanged();
+      }
+      usageSpan.end({
+        reason,
+        samples: refreshed.samples,
+        changed: refreshed.changed,
+      });
+    } finally {
+      this.refreshInFlight = false;
+    }
+  }
+}

package/src/services/recording.ts

@@ -0,0 +1,75 @@
+interface RecordingWriter {
+  close(): Promise<void>;
+}
+
+interface RenderTerminalRecordingToGifInput {
+  readonly recordingPath: string;
+  readonly outputPath: string;
+}
+
+interface RecordingServiceOptions {
+  readonly recordingWriter: RecordingWriter | null;
+  readonly recordingPath: string | null;
+  readonly recordingGifOutputPath: string | null;
+  readonly renderTerminalRecordingToGif: (
+    input: RenderTerminalRecordingToGifInput,
+  ) => Promise<unknown>;
+  readonly writeStderr: (text: string) => void;
+}
+
+export class RecordingService {
+  constructor(private readonly options: RecordingServiceOptions) {}
+
+  async closeWriter(): Promise<unknown | null> {
+    if (this.options.recordingWriter === null) {
+      return null;
+    }
+    try {
+      await this.options.recordingWriter.close();
+      return null;
+    } catch (error: unknown) {
+      return error;
+    }
+  }
+
+  async finalizeAfterShutdown(recordingCloseError: unknown | null): Promise<void> {
+    if (
+      this.options.recordingGifOutputPath !== null &&
+      this.options.recordingPath !== null &&
+      recordingCloseError === null
+    ) {
+      try {
+        await this.options.renderTerminalRecordingToGif({
+          recordingPath: this.options.recordingPath,
+          outputPath: this.options.recordingGifOutputPath,
+        });
+        this.options.writeStderr(
+          `[mux-recording] jsonl=${this.options.recordingPath} gif=${this.options.recordingGifOutputPath}\n`,
+        );
+      } catch (error: unknown) {
+        this.options.writeStderr(
+          `[mux-recording] gif-export-failed ${
+            error instanceof Error ? error.message : String(error)
+          }\n`,
+        );
+      }
+      return;
+    }
+
+    if (recordingCloseError !== null) {
+      this.options.writeStderr(
+        `[mux-recording] close-failed ${this.formatCloseError(recordingCloseError)}\n`,
+      );
+    }
+  }
+
+  private formatCloseError(recordingCloseError: unknown): string {
+    if (recordingCloseError instanceof Error) {
+      return recordingCloseError.message;
+    }
+    if (typeof recordingCloseError === 'string') {
+      return recordingCloseError;
+    }
+    return 'unknown error';
+  }
+}

package/src/services/render-trace-recorder.ts

@@ -0,0 +1,177 @@
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import {
+  parseActiveRenderTraceState,
+  type ActiveRenderTraceState,
+} from '../mux/live-mux/render-trace-state.ts';
+
+export interface RenderTraceLabels {
+  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 RenderTraceRecordInput {
+  readonly direction: 'incoming' | 'outgoing';
+  readonly source: string;
+  readonly eventType: string;
+  readonly labels: RenderTraceLabels;
+  readonly payload: unknown;
+  readonly dedupeKey?: string;
+  readonly dedupeValue?: string;
+}
+
+interface RenderTraceRecorderOptions {
+  readonly statePath: string;
+  readonly nowMs?: () => number;
+  readonly nowIso?: () => string;
+  readonly refreshIntervalMs?: number;
+}
+
+const DEFAULT_REFRESH_INTERVAL_MS = 250;
+
+export class RenderTraceRecorder {
+  private readonly nowMs: () => number;
+  private readonly nowIso: () => string;
+  private readonly refreshIntervalMs: number;
+  private nextRefreshAtMs = 0;
+  private activeState: ActiveRenderTraceState | null = null;
+  private activeOutputPath: string | null = null;
+  private outputFd: number | null = null;
+  private readonly dedupeValueByKey = new Map<string, string>();
+
+  constructor(private readonly options: RenderTraceRecorderOptions) {
+    this.nowMs = options.nowMs ?? Date.now;
+    this.nowIso = options.nowIso ?? (() => new Date().toISOString());
+    this.refreshIntervalMs = options.refreshIntervalMs ?? DEFAULT_REFRESH_INTERVAL_MS;
+  }
+
+  isActive(): boolean {
+    this.refreshIfDue();
+    return this.outputFd !== null && this.activeState !== null;
+  }
+
+  shouldCaptureConversation(conversationId: string | null): boolean {
+    this.refreshIfDue();
+    if (this.outputFd === null || this.activeState === null) {
+      return false;
+    }
+    if (this.activeState.conversationId === null) {
+      return true;
+    }
+    return conversationId === this.activeState.conversationId;
+  }
+
+  record(input: RenderTraceRecordInput): void {
+    this.refreshIfDue();
+    if (this.outputFd === null || this.activeState === null) {
+      return;
+    }
+    if (!this.matchesConversationFilter(input.labels, this.activeState)) {
+      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,
+      filterConversationId: this.activeState.conversationId,
+    };
+    try {
+      writeSync(this.outputFd, `${JSON.stringify(record)}\n`);
+    } catch {
+      this.deactivate();
+    }
+  }
+
+  close(): void {
+    this.deactivate();
+  }
+
+  private matchesConversationFilter(
+    labels: RenderTraceLabels,
+    state: ActiveRenderTraceState,
+  ): boolean {
+    if (state.conversationId === null) {
+      return true;
+    }
+    if (labels.conversationId === state.conversationId) {
+      return true;
+    }
+    return labels.threadId === state.conversationId;
+  }
+
+  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: ActiveRenderTraceState, 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(): ActiveRenderTraceState | null {
+    if (!existsSync(this.options.statePath)) {
+      return null;
+    }
+    try {
+      const raw = JSON.parse(readFileSync(this.options.statePath, 'utf8')) as unknown;
+      return parseActiveRenderTraceState(raw);
+    } catch {
+      return null;
+    }
+  }
+}

package/src/services/runtime-control-actions.ts

@@ -0,0 +1,123 @@
+interface RuntimeInterruptResult {
+  readonly interrupted: boolean;
+}
+
+interface RuntimeConversationControlState {
+  live: boolean;
+  status: string;
+  attentionReason: string | null;
+  lastEventAt: string | null;
+}
+
+interface RuntimeGatewayProfilerResult {
+  readonly message: string;
+}
+
+interface RuntimeGatewayStatusTimelineResult {
+  readonly message: string;
+}
+
+interface RuntimeGatewayRenderTraceResult {
+  readonly message: string;
+}
+
+interface RuntimeControlActionsOptions<TConversation extends RuntimeConversationControlState> {
+  readonly conversationById: (sessionId: string) => TConversation | undefined;
+  readonly interruptSession: (sessionId: string) => Promise<RuntimeInterruptResult>;
+  readonly nowIso: () => string;
+  readonly markDirty: () => void;
+  readonly toggleGatewayProfiler: (input: {
+    invocationDirectory: string;
+    sessionName: string | null;
+  }) => Promise<RuntimeGatewayProfilerResult>;
+  readonly toggleGatewayStatusTimeline: (input: {
+    invocationDirectory: string;
+    sessionName: string | null;
+  }) => Promise<RuntimeGatewayStatusTimelineResult>;
+  readonly toggleGatewayRenderTrace: (input: {
+    invocationDirectory: string;
+    sessionName: string | null;
+    conversationId: string | null;
+  }) => Promise<RuntimeGatewayRenderTraceResult>;
+  readonly invocationDirectory: string;
+  readonly sessionName: string | null;
+  readonly setTaskPaneNotice: (message: string) => void;
+  readonly setDebugFooterNotice: (message: string) => void;
+}
+
+export class RuntimeControlActions<TConversation extends RuntimeConversationControlState> {
+  constructor(private readonly options: RuntimeControlActionsOptions<TConversation>) {}
+
+  async interruptConversation(sessionId: string): Promise<void> {
+    const conversation = this.options.conversationById(sessionId);
+    if (conversation === undefined || !conversation.live) {
+      return;
+    }
+    const result = await this.options.interruptSession(sessionId);
+    if (!result.interrupted) {
+      return;
+    }
+    conversation.status = 'completed';
+    conversation.attentionReason = null;
+    conversation.lastEventAt = this.options.nowIso();
+    this.options.markDirty();
+  }
+
+  async toggleGatewayProfiler(): Promise<void> {
+    try {
+      const result = await this.options.toggleGatewayProfiler({
+        invocationDirectory: this.options.invocationDirectory,
+        sessionName: this.options.sessionName,
+      });
+      this.setNotices(this.scopeMessage('profile', result.message));
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.setNotices(this.scopeMessage('profile', message));
+    } finally {
+      this.options.markDirty();
+    }
+  }
+
+  async toggleGatewayStatusTimeline(): Promise<void> {
+    try {
+      const result = await this.options.toggleGatewayStatusTimeline({
+        invocationDirectory: this.options.invocationDirectory,
+        sessionName: this.options.sessionName,
+      });
+      this.setNotices(this.scopeMessage('status-trace', result.message));
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.setNotices(this.scopeMessage('status-trace', message));
+    } finally {
+      this.options.markDirty();
+    }
+  }
+
+  async toggleGatewayRenderTrace(conversationId: string | null): Promise<void> {
+    try {
+      const result = await this.options.toggleGatewayRenderTrace({
+        invocationDirectory: this.options.invocationDirectory,
+        sessionName: this.options.sessionName,
+        conversationId,
+      });
+      this.setNotices(this.scopeMessage('render-trace', result.message));
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.setNotices(this.scopeMessage('render-trace', message));
+    } finally {
+      this.options.markDirty();
+    }
+  }
+
+  private scopeMessage(prefix: string, message: string): string {
+    if (this.options.sessionName === null) {
+      return `[${prefix}] ${message}`;
+    }
+    return `[${prefix}:${this.options.sessionName}] ${message}`;
+  }
+
+  private setNotices(message: string): void {
+    this.options.setTaskPaneNotice(message);
+    this.options.setDebugFooterNotice(message);
+  }
+}

package/src/services/runtime-control-plane-ops.ts

@@ -0,0 +1,131 @@
+import { ControlPlaneOpQueue } from '../mux/control-plane-op-queue.ts';
+
+type PerfAttrValue = boolean | number | string;
+type PerfAttrs = Readonly<Record<string, PerfAttrValue>>;
+
+interface RuntimeControlPlaneOpEvent {
+  readonly id: number;
+  readonly priority: 'interactive' | 'background';
+  readonly label: string;
+  readonly waitMs: number;
+}
+
+interface RuntimeControlPlaneOpsOptions {
+  readonly onFatal: (error: unknown) => void;
+  readonly startPerfSpan: (
+    name: string,
+    attrs?: PerfAttrs,
+    parentSpanId?: string,
+  ) => { end: (attrs?: PerfAttrs) => void };
+  readonly recordPerfEvent: (name: string, attrs?: PerfAttrs) => void;
+  readonly writeStderr: (text: string) => void;
+  readonly nowMs?: () => number;
+  readonly schedule?: (callback: () => void) => void;
+}
+
+export class RuntimeControlPlaneOps {
+  private readonly opSpans = new Map<
+    number,
+    {
+      end: (attrs?: PerfAttrs) => void;
+    }
+  >();
+
+  private readonly queue: ControlPlaneOpQueue;
+
+  constructor(private readonly options: RuntimeControlPlaneOpsOptions) {
+    this.queue = new ControlPlaneOpQueue({
+      ...(options.nowMs === undefined
+        ? {}
+        : {
+            nowMs: options.nowMs,
+          }),
+      ...(options.schedule === undefined
+        ? {}
+        : {
+            schedule: options.schedule,
+          }),
+      onFatal: (error: unknown) => {
+        this.options.onFatal(error);
+      },
+      onEnqueued: (event, metrics) => {
+        this.options.recordPerfEvent('mux.control-plane.op.enqueued', {
+          id: event.id,
+          label: event.label,
+          priority: event.priority,
+          interactiveQueued: metrics.interactiveQueued,
+          backgroundQueued: metrics.backgroundQueued,
+        });
+      },
+      onStart: (event, metrics) => {
+        const opSpan = this.options.startPerfSpan('mux.control-plane.op', {
+          id: event.id,
+          label: event.label,
+          priority: event.priority,
+          waitMs: event.waitMs,
+        });
+        this.opSpans.set(event.id, opSpan);
+        this.options.recordPerfEvent('mux.control-plane.op.start', {
+          id: event.id,
+          label: event.label,
+          priority: event.priority,
+          waitMs: event.waitMs,
+          interactiveQueued: metrics.interactiveQueued,
+          backgroundQueued: metrics.backgroundQueued,
+        });
+      },
+      onSuccess: (event) => {
+        this.endSpan(event, 'ok');
+      },
+      onError: (event, _metrics, error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        this.endSpan(event, 'error', message);
+        this.options.writeStderr(`[mux] control-plane error ${message}\n`);
+      },
+    });
+  }
+
+  enqueueInteractive(task: () => Promise<void>, label = 'interactive-op'): void {
+    this.queue.enqueueInteractive(task, label);
+  }
+
+  enqueueBackground(task: () => Promise<void>, label = 'background-op'): void {
+    this.queue.enqueueBackground(task, label);
+  }
+
+  async waitForDrain(): Promise<void> {
+    await this.queue.waitForDrain();
+  }
+
+  metrics(): {
+    readonly interactiveQueued: number;
+    readonly backgroundQueued: number;
+    readonly running: boolean;
+  } {
+    return this.queue.metrics();
+  }
+
+  private endSpan(
+    event: RuntimeControlPlaneOpEvent,
+    status: 'ok' | 'error',
+    message?: string,
+  ): void {
+    const opSpan = this.opSpans.get(event.id);
+    if (opSpan === undefined) {
+      return;
+    }
+    opSpan.end({
+      id: event.id,
+      label: event.label,
+      priority: event.priority,
+      status,
+      waitMs: event.waitMs,
+      ...(message === undefined
+        ? {}
+        : {
+            message,
+          }),
+    });
+    this.opSpans.delete(event.id);
+  }
+}

package/src/services/runtime-conversation-actions.ts

@@ -0,0 +1,113 @@
+import {
+  createAndActivateConversationInDirectory as createAndActivateConversationInDirectoryFn,
+  openOrCreateCritiqueConversationInDirectory as openOrCreateCritiqueConversationInDirectoryFn,
+  takeoverConversation as takeoverConversationFn,
+} from '../mux/live-mux/actions-conversation.ts';
+
+interface RuntimeConversationRecord {
+  readonly directoryId: string | null;
+  readonly agentType: string;
+}
+
+interface RuntimeConversationActionService<TControllerRecord> {
+  createConversation(input: {
+    conversationId: string;
+    directoryId: string;
+    title: string;
+    agentType: string;
+    adapterState: Record<string, unknown>;
+  }): Promise<unknown>;
+  claimSession(input: {
+    sessionId: string;
+    controllerId: string;
+    controllerType: string;
+    controllerLabel: string;
+    reason: string;
+    takeover: boolean;
+  }): Promise<TControllerRecord | null>;
+}
+
+export interface RuntimeConversationActionsOptions<TControllerRecord> {
+  readonly controlPlaneService: RuntimeConversationActionService<TControllerRecord>;
+  readonly createConversationId: () => string;
+  readonly ensureConversation: (
+    sessionId: string,
+    seed: {
+      directoryId: string;
+      title: string;
+      agentType: string;
+      adapterState: Record<string, unknown>;
+    },
+  ) => void;
+  readonly noteGitActivity: (directoryId: string) => void;
+  readonly startConversation: (sessionId: string) => Promise<unknown>;
+  readonly activateConversation: (sessionId: string) => Promise<unknown>;
+  readonly orderedConversationIds: () => readonly string[];
+  readonly conversationById: (sessionId: string) => RuntimeConversationRecord | null;
+  readonly conversationsHas: (sessionId: string) => boolean;
+  readonly applyController: (sessionId: string, controller: TControllerRecord) => void;
+  readonly setLastEventNow: (sessionId: string) => void;
+  readonly muxControllerId: string;
+  readonly muxControllerLabel: string;
+  readonly markDirty: () => void;
+}
+
+export class RuntimeConversationActions<TControllerRecord> {
+  constructor(private readonly options: RuntimeConversationActionsOptions<TControllerRecord>) {}
+
+  async createAndActivateConversationInDirectory(
+    directoryId: string,
+    agentType: string,
+  ): Promise<void> {
+    await createAndActivateConversationInDirectoryFn({
+      directoryId,
+      agentType,
+      createConversationId: this.options.createConversationId,
+      createConversationRecord: async (sessionId, targetDirectoryId, targetAgentType) => {
+        await this.options.controlPlaneService.createConversation({
+          conversationId: sessionId,
+          directoryId: targetDirectoryId,
+          title: '',
+          agentType: String(targetAgentType),
+          adapterState: {},
+        });
+      },
+      ensureConversation: this.options.ensureConversation,
+      noteGitActivity: this.options.noteGitActivity,
+      startConversation: this.options.startConversation,
+      activateConversation: this.options.activateConversation,
+    });
+  }
+
+  async openOrCreateCritiqueConversationInDirectory(directoryId: string): Promise<void> {
+    await openOrCreateCritiqueConversationInDirectoryFn({
+      directoryId,
+      orderedConversationIds: this.options.orderedConversationIds,
+      conversationById: this.options.conversationById,
+      activateConversation: this.options.activateConversation,
+      createAndActivateCritiqueConversationInDirectory: async (targetDirectoryId) => {
+        await this.createAndActivateConversationInDirectory(targetDirectoryId, 'critique');
+      },
+    });
+  }
+
+  async takeoverConversation(sessionId: string): Promise<void> {
+    await takeoverConversationFn({
+      sessionId,
+      conversationsHas: this.options.conversationsHas,
+      claimSession: async (targetSessionId) => {
+        return await this.options.controlPlaneService.claimSession({
+          sessionId: targetSessionId,
+          controllerId: this.options.muxControllerId,
+          controllerType: 'human',
+          controllerLabel: this.options.muxControllerLabel,
+          reason: 'human takeover',
+          takeover: true,
+        });
+      },
+      applyController: this.options.applyController,
+      setLastEventNow: this.options.setLastEventNow,
+      markDirty: this.options.markDirty,
+    });
+  }
+}