@jmoyers/harness 0.1.0

package/src/mux/live-mux/conversation-state.ts

@@ -0,0 +1,188 @@
+import { resolveTerminalCommandForEnvironment } from '../../control-plane/stream-server.ts';
+import type { parseSessionSummaryRecord } from '../../control-plane/session-summary.ts';
+import type {
+  StreamSessionController,
+  StreamSessionStatusModel,
+} from '../../control-plane/stream-protocol.ts';
+import type { EventScope } from '../../events/normalized-events.ts';
+import type { PtyExit } from '../../pty/pty_host.ts';
+import { TerminalSnapshotOracle } from '../../terminal/snapshot-oracle.ts';
+import { type ConversationRailSessionSummary } from '../conversation-rail.ts';
+import { normalizeThreadAgentType } from '../new-thread-prompt.ts';
+
+type SessionSummaryRecord = NonNullable<ReturnType<typeof parseSessionSummaryRecord>>;
+
+export interface ConversationState {
+  readonly sessionId: string;
+  directoryId: string | null;
+  title: string;
+  agentType: string;
+  adapterState: Record<string, unknown>;
+  turnId: string;
+  scope: EventScope;
+  oracle: TerminalSnapshotOracle;
+  status: ConversationRailSessionSummary['status'];
+  statusModel: StreamSessionStatusModel | null;
+  attentionReason: string | null;
+  startedAt: string;
+  lastEventAt: string | null;
+  exitedAt: string | null;
+  lastExit: PtyExit | null;
+  processId: number | null;
+  live: boolean;
+  attached: boolean;
+  launchCommand: string | null;
+  lastOutputCursor: number;
+  lastKnownWork: string | null;
+  lastKnownWorkAt: string | null;
+  lastTelemetrySource: string | null;
+  controller: StreamSessionController | null;
+}
+
+function createConversationScope(
+  baseScope: EventScope,
+  conversationId: string,
+  turnId: string,
+): EventScope {
+  return {
+    tenantId: baseScope.tenantId,
+    userId: baseScope.userId,
+    workspaceId: baseScope.workspaceId,
+    worktreeId: baseScope.worktreeId,
+    conversationId,
+    turnId,
+  };
+}
+
+export function createConversationState(
+  sessionId: string,
+  directoryId: string | null,
+  title: string,
+  agentType: string,
+  adapterState: Record<string, unknown>,
+  turnId: string,
+  baseScope: EventScope,
+  cols: number,
+  rows: number,
+): ConversationState {
+  const startedAt = new Date().toISOString();
+  const statusModel: StreamSessionStatusModel | null = null;
+  return {
+    sessionId,
+    directoryId,
+    title,
+    agentType,
+    adapterState,
+    turnId,
+    scope: createConversationScope(baseScope, sessionId, turnId),
+    oracle: new TerminalSnapshotOracle(cols, rows),
+    status: 'running',
+    statusModel,
+    attentionReason: null,
+    startedAt,
+    lastEventAt: null,
+    exitedAt: null,
+    lastExit: null,
+    processId: null,
+    live: true,
+    attached: false,
+    launchCommand: null,
+    lastOutputCursor: 0,
+    lastKnownWork: null,
+    lastKnownWorkAt: null,
+    lastTelemetrySource: null,
+    controller: null,
+  };
+}
+
+export function applySummaryToConversation(
+  target: ConversationState,
+  summary: SessionSummaryRecord | null,
+): void {
+  if (summary === null) {
+    return;
+  }
+  target.scope.tenantId = summary.tenantId;
+  target.scope.userId = summary.userId;
+  target.scope.workspaceId = summary.workspaceId;
+  target.scope.worktreeId = summary.worktreeId;
+  target.directoryId = summary.directoryId;
+  target.status = summary.status;
+  target.statusModel = summary.statusModel;
+  target.attentionReason = summary.attentionReason;
+  target.startedAt = summary.startedAt;
+  target.lastEventAt = summary.lastEventAt;
+  target.exitedAt = summary.exitedAt;
+  target.lastExit = summary.lastExit;
+  target.processId = summary.processId;
+  target.live = summary.live;
+  target.controller = summary.controller;
+  const statusModel = summary.statusModel;
+  target.lastKnownWork = statusModel?.lastKnownWork ?? null;
+  target.lastKnownWorkAt = statusModel?.lastKnownWorkAt ?? null;
+}
+
+export function conversationSummary(
+  conversation: ConversationState,
+): ConversationRailSessionSummary {
+  return {
+    sessionId: conversation.sessionId,
+    status: conversation.status,
+    statusModel: conversation.statusModel,
+    attentionReason: conversation.attentionReason,
+    live: conversation.live,
+    startedAt: conversation.startedAt,
+    lastEventAt: conversation.lastEventAt,
+  };
+}
+
+export function compactDebugText(value: string | null): string {
+  if (value === null) {
+    return '';
+  }
+  const normalized = value.replace(/\s+/gu, ' ').trim();
+  if (normalized.length <= 160) {
+    return normalized;
+  }
+  return `${normalized.slice(0, 159)}…`;
+}
+
+function shellQuoteToken(token: string): string {
+  if (token.length === 0) {
+    return "''";
+  }
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/u.test(token)) {
+    return token;
+  }
+  return `'${token.replaceAll("'", "'\"'\"'")}'`;
+}
+
+export function formatCommandForDebugBar(command: string, args: readonly string[]): string {
+  const tokens = [command, ...args].map(shellQuoteToken);
+  return tokens.join(' ');
+}
+
+export function launchCommandForAgent(agentType: string): string {
+  const normalized = normalizeThreadAgentType(agentType);
+  if (normalized === 'claude') {
+    return 'claude';
+  }
+  if (normalized === 'critique') {
+    return 'critique';
+  }
+  if (normalized === 'cursor') {
+    return 'cursor-agent';
+  }
+  if (normalized === 'terminal') {
+    return resolveTerminalCommandForEnvironment(process.env, process.platform);
+  }
+  return 'codex';
+}
+
+export function debugFooterForConversation(conversation: ConversationState): string {
+  const launchCommand =
+    conversation.launchCommand === null
+      ? '(launch command unavailable)'
+      : compactDebugText(conversation.launchCommand);
+  return `[dbg] ${launchCommand}`;
+}

package/src/mux/live-mux/directory-resolution.ts

@@ -0,0 +1,34 @@
+interface ResolveDirectoryForActionConversationState {
+  readonly directoryId: string | null;
+}
+
+interface ResolveDirectoryForActionOptions {
+  mainPaneMode: 'conversation' | 'project' | 'home';
+  activeDirectoryId: string | null;
+  activeConversationId: string | null;
+  conversations: ReadonlyMap<string, ResolveDirectoryForActionConversationState>;
+  directoriesHas: (directoryId: string) => boolean;
+}
+
+export function resolveDirectoryForAction(
+  options: ResolveDirectoryForActionOptions,
+): string | null {
+  if (options.mainPaneMode === 'project') {
+    if (options.activeDirectoryId !== null && options.directoriesHas(options.activeDirectoryId)) {
+      return options.activeDirectoryId;
+    }
+    return null;
+  }
+  if (options.activeConversationId !== null) {
+    const conversation = options.conversations.get(options.activeConversationId);
+    if (conversation?.directoryId !== null && conversation?.directoryId !== undefined) {
+      if (options.directoriesHas(conversation.directoryId)) {
+        return conversation.directoryId;
+      }
+    }
+  }
+  if (options.activeDirectoryId !== null && options.directoriesHas(options.activeDirectoryId)) {
+    return options.activeDirectoryId;
+  }
+  return null;
+}

package/src/mux/live-mux/event-mapping.ts

@@ -0,0 +1,96 @@
+import type { EventScope, NormalizedEventEnvelope } from '../../events/normalized-events.ts';
+import { createNormalizedEvent } from '../../events/normalized-events.ts';
+import type { PtyExit } from '../../pty/pty_host.ts';
+import type { StreamSessionEvent } from '../../control-plane/stream-protocol.ts';
+
+export function normalizeExitCode(exit: PtyExit): number {
+  if (exit.code !== null) {
+    return exit.code;
+  }
+  if (exit.signal !== null) {
+    return 128;
+  }
+  return 1;
+}
+
+export function isSessionNotFoundError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return /session not found/i.test(error.message);
+}
+
+export function isSessionNotLiveError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return /session is not live/i.test(error.message);
+}
+
+export function isConversationNotFoundError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return /conversation not found/i.test(error.message);
+}
+
+export function mapTerminalOutputToNormalizedEvent(
+  chunk: Buffer,
+  scope: EventScope,
+  idFactory: () => string,
+): NormalizedEventEnvelope {
+  return createNormalizedEvent(
+    'provider',
+    'provider-text-delta',
+    scope,
+    {
+      kind: 'text-delta',
+      threadId: scope.conversationId,
+      turnId: scope.turnId ?? 'turn-live',
+      delta: chunk.toString('utf8'),
+    },
+    () => new Date(),
+    idFactory,
+  );
+}
+
+export function mapSessionEventToNormalizedEvent(
+  event: StreamSessionEvent,
+  scope: EventScope,
+  idFactory: () => string,
+): NormalizedEventEnvelope | null {
+  if (event.type === 'session-exit') {
+    return createNormalizedEvent(
+      'meta',
+      'meta-attention-cleared',
+      scope,
+      {
+        kind: 'attention',
+        threadId: scope.conversationId,
+        turnId: scope.turnId ?? 'turn-live',
+        reason: 'stalled',
+        detail: 'session-exit',
+      },
+      () => new Date(),
+      idFactory,
+    );
+  }
+
+  return null;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== 'object' || value === null) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+export function observedAtFromSessionEvent(event: StreamSessionEvent): string {
+  if (event.type === 'session-exit') {
+    return new Date().toISOString();
+  }
+  const record = asRecord((event as { record?: unknown }).record);
+  const ts = record?.['ts'];
+  return typeof ts === 'string' ? ts : new Date().toISOString();
+}

package/src/mux/live-mux/gateway-profiler.ts

@@ -0,0 +1,152 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+type GatewayProfilerAction = 'start' | 'stop';
+
+interface RunHarnessProfileCommandInput {
+  readonly invocationDirectory: string;
+  readonly harnessScriptPath: string;
+  readonly sessionName: string | null;
+  readonly action: GatewayProfilerAction;
+}
+
+interface RunHarnessProfileCommandResult {
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+interface ToggleGatewayProfilerOptions {
+  readonly invocationDirectory: string;
+  readonly sessionName: string | null;
+  readonly profileStateExists?: (profileStatePath: string) => boolean;
+  readonly runHarnessProfileCommand?: (
+    input: RunHarnessProfileCommandInput,
+  ) => Promise<RunHarnessProfileCommandResult>;
+  readonly harnessScriptPath?: string;
+}
+
+interface ToggleGatewayProfilerResult {
+  readonly action: GatewayProfilerAction;
+  readonly message: string;
+  readonly stdout: string;
+}
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_HARNESS_SCRIPT_PATH = resolve(SCRIPT_DIR, '../../../scripts/harness.ts');
+
+function firstNonEmptyLine(text: string): string | null {
+  const lines = text
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  return lines[0] ?? null;
+}
+
+export function resolveProfileStatePath(
+  invocationDirectory: string,
+  sessionName: string | null,
+): string {
+  if (sessionName === null) {
+    return resolve(invocationDirectory, '.harness', 'active-profile.json');
+  }
+  return resolve(invocationDirectory, '.harness', 'sessions', sessionName, 'active-profile.json');
+}
+
+export function resolveHarnessProfileCommandArgs(
+  action: GatewayProfilerAction,
+  sessionName: string | null,
+): readonly string[] {
+  if (sessionName === null) {
+    return ['profile', action];
+  }
+  return ['--session', sessionName, 'profile', action];
+}
+
+function summarizeProfileSuccess(action: GatewayProfilerAction, stdout: string): string {
+  const firstLine = firstNonEmptyLine(stdout);
+  if (firstLine !== null) {
+    return firstLine;
+  }
+  if (action === 'start') {
+    return 'profile started';
+  }
+  return 'profile stopped';
+}
+
+function summarizeProfileFailure(
+  action: GatewayProfilerAction,
+  stderr: string,
+  stdout: string,
+): string {
+  const detail = firstNonEmptyLine(stderr) ?? firstNonEmptyLine(stdout) ?? 'unknown error';
+  return `profile ${action} failed: ${detail}`;
+}
+
+async function runHarnessProfileCommand(
+  input: RunHarnessProfileCommandInput,
+): Promise<RunHarnessProfileCommandResult> {
+  const commandArgs = resolveHarnessProfileCommandArgs(input.action, input.sessionName);
+  const child = spawn(process.execPath, [input.harnessScriptPath, ...commandArgs], {
+    cwd: input.invocationDirectory,
+    env: {
+      ...process.env,
+      HARNESS_INVOKE_CWD: input.invocationDirectory,
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const stdoutChunks: Buffer[] = [];
+  const stderrChunks: Buffer[] = [];
+  child.stdout?.on('data', (chunk: Buffer | string) => {
+    stdoutChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  });
+  child.stderr?.on('data', (chunk: Buffer | string) => {
+    stderrChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  });
+
+  const [code, signal] = await new Promise<[number | null, NodeJS.Signals | null]>(
+    (resolveExit, rejectExit) => {
+      child.once('error', rejectExit);
+      child.once('exit', (exitCode, exitSignal) => {
+        resolveExit([exitCode, exitSignal]);
+      });
+    },
+  );
+
+  const stdout = Buffer.concat(stdoutChunks).toString('utf8');
+  const stderr = Buffer.concat(stderrChunks).toString('utf8');
+  const exitCode = code ?? (signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 1);
+  if (exitCode !== 0) {
+    throw new Error(summarizeProfileFailure(input.action, stderr, stdout));
+  }
+
+  return {
+    stdout,
+    stderr,
+  };
+}
+
+export async function toggleGatewayProfiler(
+  options: ToggleGatewayProfilerOptions,
+): Promise<ToggleGatewayProfilerResult> {
+  const profileStatePath = resolveProfileStatePath(
+    options.invocationDirectory,
+    options.sessionName,
+  );
+  const isProfileRunning = (options.profileStateExists ?? existsSync)(profileStatePath);
+  const action: GatewayProfilerAction = isProfileRunning ? 'stop' : 'start';
+  const harnessScriptPath = options.harnessScriptPath ?? DEFAULT_HARNESS_SCRIPT_PATH;
+  const runCommand = options.runHarnessProfileCommand ?? runHarnessProfileCommand;
+  const result = await runCommand({
+    invocationDirectory: options.invocationDirectory,
+    harnessScriptPath,
+    sessionName: options.sessionName,
+    action,
+  });
+  return {
+    action,
+    message: summarizeProfileSuccess(action, result.stdout),
+    stdout: result.stdout,
+  };
+}

package/src/mux/live-mux/gateway-render-trace.ts

@@ -0,0 +1,177 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveRenderTraceStatePath } from './render-trace-state.ts';
+
+type GatewayRenderTraceAction = 'start' | 'stop';
+
+interface RunHarnessRenderTraceCommandInput {
+  readonly invocationDirectory: string;
+  readonly harnessScriptPath: string;
+  readonly sessionName: string | null;
+  readonly conversationId: string | null;
+  readonly action: GatewayRenderTraceAction;
+}
+
+interface RunHarnessRenderTraceCommandResult {
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+interface ToggleGatewayRenderTraceOptions {
+  readonly invocationDirectory: string;
+  readonly sessionName: string | null;
+  readonly conversationId: string | null;
+  readonly renderTraceStateExists?: (renderTraceStatePath: string) => boolean;
+  readonly runHarnessRenderTraceCommand?: (
+    input: RunHarnessRenderTraceCommandInput,
+  ) => Promise<RunHarnessRenderTraceCommandResult>;
+  readonly harnessScriptPath?: string;
+}
+
+interface ToggleGatewayRenderTraceResult {
+  readonly action: GatewayRenderTraceAction;
+  readonly message: string;
+  readonly stdout: string;
+}
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_HARNESS_SCRIPT_PATH = resolve(SCRIPT_DIR, '../../../scripts/harness.ts');
+
+function firstNonEmptyLine(text: string): string | null {
+  const lines = text
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  return lines[0] ?? null;
+}
+
+function lineValueForPrefix(text: string, prefix: string): string | null {
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim();
+    if (!line.startsWith(prefix)) {
+      continue;
+    }
+    const value = line.slice(prefix.length).trim();
+    if (value.length === 0) {
+      continue;
+    }
+    return value;
+  }
+  return null;
+}
+
+export function resolveHarnessRenderTraceCommandArgs(
+  action: GatewayRenderTraceAction,
+  sessionName: string | null,
+  conversationId: string | null,
+): readonly string[] {
+  const base =
+    sessionName === null
+      ? ['render-trace', action]
+      : ['--session', sessionName, 'render-trace', action];
+  if (action === 'start' && conversationId !== null) {
+    return [...base, '--conversation-id', conversationId];
+  }
+  return base;
+}
+
+function summarizeRenderTraceSuccess(action: GatewayRenderTraceAction, stdout: string): string {
+  if (action === 'start') {
+    const outputPath = lineValueForPrefix(stdout, 'render-trace-target:');
+    const conversationId = lineValueForPrefix(stdout, 'render-trace-conversation-id:');
+    if (outputPath !== null && conversationId !== null) {
+      return `render: trace=${outputPath} conversation=${conversationId}`;
+    }
+    if (outputPath !== null) {
+      return `render: trace=${outputPath}`;
+    }
+  }
+  const firstLine = firstNonEmptyLine(stdout);
+  if (firstLine !== null) {
+    return firstLine;
+  }
+  if (action === 'start') {
+    return 'render trace started';
+  }
+  return 'render trace stopped';
+}
+
+function summarizeRenderTraceFailure(
+  action: GatewayRenderTraceAction,
+  stderr: string,
+  stdout: string,
+): string {
+  const detail = firstNonEmptyLine(stderr) ?? firstNonEmptyLine(stdout) ?? 'unknown error';
+  return `render trace ${action} failed: ${detail}`;
+}
+
+async function runHarnessRenderTraceCommand(
+  input: RunHarnessRenderTraceCommandInput,
+): Promise<RunHarnessRenderTraceCommandResult> {
+  const commandArgs = resolveHarnessRenderTraceCommandArgs(
+    input.action,
+    input.sessionName,
+    input.conversationId,
+  );
+  const child = spawn(process.execPath, [input.harnessScriptPath, ...commandArgs], {
+    cwd: input.invocationDirectory,
+    env: {
+      ...process.env,
+      HARNESS_INVOKE_CWD: input.invocationDirectory,
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const stdoutChunks: Buffer[] = [];
+  const stderrChunks: Buffer[] = [];
+  child.stdout?.on('data', (chunk: Buffer | string) => {
+    stdoutChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  });
+  child.stderr?.on('data', (chunk: Buffer | string) => {
+    stderrChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  });
+
+  const [code, signal] = await new Promise<[number | null, NodeJS.Signals | null]>(
+    (resolveExit, rejectExit) => {
+      child.once('error', rejectExit);
+      child.once('exit', (exitCode, exitSignal) => {
+        resolveExit([exitCode, exitSignal]);
+      });
+    },
+  );
+
+  const stdout = Buffer.concat(stdoutChunks).toString('utf8');
+  const stderr = Buffer.concat(stderrChunks).toString('utf8');
+  const exitCode = code ?? (signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 1);
+  if (exitCode !== 0) {
+    throw new Error(summarizeRenderTraceFailure(input.action, stderr, stdout));
+  }
+
+  return {
+    stdout,
+    stderr,
+  };
+}
+
+export async function toggleGatewayRenderTrace(
+  options: ToggleGatewayRenderTraceOptions,
+): Promise<ToggleGatewayRenderTraceResult> {
+  const statePath = resolveRenderTraceStatePath(options.invocationDirectory, options.sessionName);
+  const isRunning = (options.renderTraceStateExists ?? existsSync)(statePath);
+  const action: GatewayRenderTraceAction = isRunning ? 'stop' : 'start';
+  const harnessScriptPath = options.harnessScriptPath ?? DEFAULT_HARNESS_SCRIPT_PATH;
+  const runCommand = options.runHarnessRenderTraceCommand ?? runHarnessRenderTraceCommand;
+  const result = await runCommand({
+    invocationDirectory: options.invocationDirectory,
+    harnessScriptPath,
+    sessionName: options.sessionName,
+    conversationId: options.conversationId,
+    action,
+  });
+  return {
+    action,
+    message: summarizeRenderTraceSuccess(action, result.stdout),
+    stdout: result.stdout,
+  };
+}