@jmoyers/harness 0.1.0

package/src/control-plane/session-summary.ts

@@ -0,0 +1,380 @@
+import type { PtyExit } from '../pty/pty_host.ts';
+import type {
+  StreamSessionController,
+  StreamSessionControllerType,
+  StreamSessionRuntimeStatus,
+  StreamSessionStatusModel,
+  StreamTelemetrySummary,
+} from './stream-protocol.ts';
+
+interface StreamSessionSummary {
+  readonly sessionId: string;
+  readonly directoryId: string | null;
+  readonly tenantId: string;
+  readonly userId: string;
+  readonly workspaceId: string;
+  readonly worktreeId: string;
+  readonly status: StreamSessionRuntimeStatus;
+  readonly attentionReason: string | null;
+  readonly statusModel: StreamSessionStatusModel | null;
+  readonly latestCursor: number | null;
+  readonly processId: number | null;
+  readonly attachedClients: number;
+  readonly eventSubscribers: number;
+  readonly startedAt: string;
+  readonly lastEventAt: string | null;
+  readonly lastExit: PtyExit | null;
+  readonly exitedAt: string | null;
+  readonly live: boolean;
+  readonly launchCommand: string | null;
+  readonly telemetry: StreamTelemetrySummary | null;
+  readonly controller: StreamSessionController | null;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== 'object' || value === null) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function readString(value: unknown): string | null {
+  return typeof value === 'string' ? value : null;
+}
+
+function readNullableString(value: unknown): string | null | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (value === null) {
+    return null;
+  }
+  if (typeof value === 'string') {
+    return value;
+  }
+  return undefined;
+}
+
+function readNullableNumber(value: unknown): number | null | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (value === null) {
+    return null;
+  }
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value;
+  }
+  return undefined;
+}
+
+function readBoolean(value: unknown): boolean | null {
+  return typeof value === 'boolean' ? value : null;
+}
+
+function readNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function readExit(value: unknown): PtyExit | null | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (value === null) {
+    return null;
+  }
+  const record = asRecord(value);
+  if (record === null) {
+    return undefined;
+  }
+  const code = readNullableNumber(record['code']);
+  const signal = readNullableString(record['signal']);
+  if (code === undefined || signal === undefined) {
+    return undefined;
+  }
+  if (signal !== null && !/^SIG[A-Z0-9]+(?:_[A-Z0-9]+)*$/.test(signal)) {
+    return undefined;
+  }
+  return {
+    code,
+    signal: signal as NodeJS.Signals | null,
+  };
+}
+
+function readTelemetrySource(
+  value: unknown,
+): 'otlp-log' | 'otlp-metric' | 'otlp-trace' | 'history' | null {
+  if (
+    value === 'otlp-log' ||
+    value === 'otlp-metric' ||
+    value === 'otlp-trace' ||
+    value === 'history'
+  ) {
+    return value;
+  }
+  return null;
+}
+
+function readTelemetrySummary(value: unknown): StreamTelemetrySummary | null | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (value === null) {
+    return null;
+  }
+  const record = asRecord(value);
+  if (record === null) {
+    return undefined;
+  }
+  const source = readTelemetrySource(record['source']);
+  const eventName = readNullableString(record['eventName']);
+  const severity = readNullableString(record['severity']);
+  const summary = readNullableString(record['summary']);
+  const observedAt = readString(record['observedAt']);
+  if (
+    source === null ||
+    eventName === undefined ||
+    severity === undefined ||
+    summary === undefined ||
+    observedAt === null
+  ) {
+    return undefined;
+  }
+  return {
+    source,
+    eventName,
+    severity,
+    summary,
+    observedAt,
+  };
+}
+
+function readSessionControllerType(value: unknown): StreamSessionControllerType | null {
+  if (value === 'human' || value === 'agent' || value === 'automation') {
+    return value;
+  }
+  return null;
+}
+
+function readSessionController(value: unknown): StreamSessionController | null | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (value === null) {
+    return null;
+  }
+  const record = asRecord(value);
+  if (record === null) {
+    return undefined;
+  }
+  const controllerId = readString(record['controllerId']);
+  const controllerType = readSessionControllerType(record['controllerType']);
+  const controllerLabel = readNullableString(record['controllerLabel']);
+  const claimedAt = readString(record['claimedAt']);
+  if (
+    controllerId === null ||
+    controllerType === null ||
+    controllerLabel === undefined ||
+    claimedAt === null
+  ) {
+    return undefined;
+  }
+  return {
+    controllerId,
+    controllerType,
+    controllerLabel,
+    claimedAt,
+  };
+}
+
+function readSessionStatusModel(value: unknown): StreamSessionStatusModel | null | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (value === null) {
+    return null;
+  }
+  const record = asRecord(value);
+  if (record === null) {
+    return undefined;
+  }
+  const runtimeStatus = readString(record['runtimeStatus']);
+  const phase = readString(record['phase']);
+  const glyph = readString(record['glyph']);
+  const badge = readString(record['badge']);
+  const detailText = readString(record['detailText']);
+  const attentionReason = readNullableString(record['attentionReason']);
+  const lastKnownWork = readNullableString(record['lastKnownWork']);
+  const lastKnownWorkAt = readNullableString(record['lastKnownWorkAt']);
+  const phaseHintRaw = readNullableString(record['phaseHint']);
+  const observedAt = readString(record['observedAt']);
+  if (
+    runtimeStatus === null ||
+    !isRuntimeStatus(runtimeStatus) ||
+    phase === null ||
+    (phase !== 'needs-action' &&
+      phase !== 'starting' &&
+      phase !== 'working' &&
+      phase !== 'idle' &&
+      phase !== 'exited') ||
+    glyph === null ||
+    (glyph !== '▲' && glyph !== '◔' && glyph !== '◆' && glyph !== '○' && glyph !== '■') ||
+    badge === null ||
+    (badge !== 'NEED' && badge !== 'RUN ' && badge !== 'DONE' && badge !== 'EXIT') ||
+    detailText === null ||
+    attentionReason === undefined ||
+    lastKnownWork === undefined ||
+    lastKnownWorkAt === undefined ||
+    phaseHintRaw === undefined ||
+    observedAt === null
+  ) {
+    return undefined;
+  }
+  const phaseHint =
+    phaseHintRaw === null ||
+    phaseHintRaw === 'needs-action' ||
+    phaseHintRaw === 'working' ||
+    phaseHintRaw === 'idle'
+      ? phaseHintRaw
+      : undefined;
+  if (phaseHint === undefined) {
+    return undefined;
+  }
+  return {
+    runtimeStatus,
+    phase,
+    glyph,
+    badge,
+    detailText,
+    attentionReason,
+    lastKnownWork,
+    lastKnownWorkAt,
+    phaseHint,
+    observedAt,
+  };
+}
+
+function isRuntimeStatus(value: string): value is StreamSessionRuntimeStatus {
+  return (
+    value === 'running' || value === 'needs-input' || value === 'completed' || value === 'exited'
+  );
+}
+
+export function parseSessionSummaryRecord(value: unknown): StreamSessionSummary | null {
+  const record = asRecord(value);
+  if (record === null) {
+    return null;
+  }
+  const sessionId = readString(record['sessionId']);
+  const directoryId = readNullableString(record['directoryId']);
+  const tenantId = readString(record['tenantId']);
+  const userId = readString(record['userId']);
+  const workspaceId = readString(record['workspaceId']);
+  const worktreeId = readString(record['worktreeId']);
+  const status = readString(record['status']);
+  if (
+    sessionId === null ||
+    directoryId === undefined ||
+    tenantId === null ||
+    userId === null ||
+    workspaceId === null ||
+    worktreeId === null ||
+    status === null ||
+    !isRuntimeStatus(status)
+  ) {
+    return null;
+  }
+  const attentionReason = readNullableString(record['attentionReason']);
+  const statusModel = readSessionStatusModel(record['statusModel']);
+  const latestCursor = readNullableNumber(record['latestCursor']);
+  const processId = readNullableNumber(record['processId']);
+  const attachedClients = readNumber(record['attachedClients']);
+  const eventSubscribers = readNumber(record['eventSubscribers']);
+  const startedAt = readString(record['startedAt']);
+  const lastEventAt = readNullableString(record['lastEventAt']);
+  const lastExit = readExit(record['lastExit']);
+  const exitedAt = readNullableString(record['exitedAt']);
+  const live = readBoolean(record['live']);
+  const launchCommand = readNullableString(record['launchCommand']);
+  const telemetry = readTelemetrySummary(record['telemetry']);
+  const controller = readSessionController(record['controller']);
+  if (attentionReason === undefined) {
+    return null;
+  }
+  if (statusModel === undefined) {
+    return null;
+  }
+  if (latestCursor === undefined) {
+    return null;
+  }
+  if (processId === undefined) {
+    return null;
+  }
+  if (attachedClients === null) {
+    return null;
+  }
+  if (eventSubscribers === null) {
+    return null;
+  }
+  if (startedAt === null) {
+    return null;
+  }
+  if (lastEventAt === undefined) {
+    return null;
+  }
+  if (lastExit === undefined) {
+    return null;
+  }
+  if (exitedAt === undefined) {
+    return null;
+  }
+  if (live === null) {
+    return null;
+  }
+  if (launchCommand === undefined) {
+    return null;
+  }
+  if (telemetry === undefined) {
+    return null;
+  }
+  if (controller === undefined) {
+    return null;
+  }
+  return {
+    sessionId,
+    directoryId,
+    tenantId,
+    userId,
+    workspaceId,
+    worktreeId,
+    status,
+    attentionReason,
+    statusModel,
+    latestCursor,
+    processId,
+    attachedClients,
+    eventSubscribers,
+    startedAt,
+    lastEventAt,
+    lastExit,
+    exitedAt,
+    live,
+    launchCommand,
+    telemetry: telemetry ?? null,
+    controller: controller ?? null,
+  };
+}
+
+export function parseSessionSummaryList(value: unknown): readonly StreamSessionSummary[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const parsed: StreamSessionSummary[] = [];
+  for (const entry of value) {
+    const summary = parseSessionSummaryRecord(entry);
+    if (summary !== null) {
+      parsed.push(summary);
+    }
+  }
+  return parsed;
+}

package/src/control-plane/status/agent-status-reducer.ts

@@ -0,0 +1,21 @@
+import type {
+  StreamSessionRuntimeStatus,
+  StreamSessionStatusModel,
+  StreamTelemetrySummary,
+} from '../stream-protocol.ts';
+
+export interface AgentStatusProjectionInput {
+  readonly runtimeStatus: StreamSessionRuntimeStatus;
+  readonly attentionReason: string | null;
+  readonly telemetry: StreamTelemetrySummary | null;
+  readonly observedAt: string;
+  readonly previous: StreamSessionStatusModel | null;
+}
+
+export interface AgentStatusReducer {
+  readonly agentType: string;
+  project(input: AgentStatusProjectionInput): StreamSessionStatusModel | null;
+}
+
+// Runtime token so coverage/deadcode tooling can account for this module.
+export const AGENT_STATUS_REDUCER_RUNTIME_TOKEN = 'agent-status-reducer';

package/src/control-plane/status/reducer-base.ts

@@ -0,0 +1,170 @@
+import type {
+  StreamSessionDisplayPhase,
+  StreamSessionRuntimeStatus,
+  StreamSessionStatusModel,
+  StreamTelemetrySummary,
+} from '../stream-protocol.ts';
+import type { AgentStatusProjectionInput, AgentStatusReducer } from './agent-status-reducer.ts';
+
+interface WorkProjection {
+  readonly text: string | null;
+  readonly phaseHint: 'needs-action' | 'working' | 'idle' | null;
+}
+
+function normalizeText(value: string | null): string | null {
+  if (value === null) {
+    return null;
+  }
+  const normalized = value.replace(/\s+/gu, ' ').trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function parseIsoMs(value: string | null): number {
+  if (value === null) {
+    return Number.NaN;
+  }
+  return Date.parse(value);
+}
+
+function eventIsNewer(observedAt: string, previousObservedAt: string | null): boolean {
+  const observedAtMs = parseIsoMs(observedAt);
+  const previousAtMs = parseIsoMs(previousObservedAt);
+  if (!Number.isFinite(previousAtMs) || !Number.isFinite(observedAtMs)) {
+    return true;
+  }
+  return observedAtMs >= previousAtMs;
+}
+
+function phaseFromRuntimeStatus(
+  runtimeStatus: StreamSessionRuntimeStatus,
+  phaseHint: WorkProjection['phaseHint'],
+): StreamSessionDisplayPhase {
+  if (runtimeStatus === 'needs-input') {
+    return 'needs-action';
+  }
+  if (runtimeStatus === 'exited') {
+    return 'exited';
+  }
+  if (phaseHint === 'working') {
+    return 'working';
+  }
+  if (phaseHint === 'needs-action') {
+    return 'needs-action';
+  }
+  if (phaseHint === 'idle') {
+    return 'idle';
+  }
+  if (runtimeStatus === 'running') {
+    return 'starting';
+  }
+  return 'idle';
+}
+
+function defaultTextForPhase(phase: StreamSessionDisplayPhase): string {
+  if (phase === 'needs-action') {
+    return 'needs input';
+  }
+  if (phase === 'starting') {
+    return 'starting';
+  }
+  if (phase === 'working') {
+    return 'active';
+  }
+  if (phase === 'exited') {
+    return 'exited';
+  }
+  return 'inactive';
+}
+
+function glyphForPhase(phase: StreamSessionDisplayPhase): StreamSessionStatusModel['glyph'] {
+  if (phase === 'needs-action') {
+    return '▲';
+  }
+  if (phase === 'starting') {
+    return '◔';
+  }
+  if (phase === 'working') {
+    return '◆';
+  }
+  if (phase === 'exited') {
+    return '■';
+  }
+  return '○';
+}
+
+function badgeForRuntimeStatus(
+  runtimeStatus: StreamSessionRuntimeStatus,
+): StreamSessionStatusModel['badge'] {
+  if (runtimeStatus === 'needs-input') {
+    return 'NEED';
+  }
+  if (runtimeStatus === 'running') {
+    return 'RUN ';
+  }
+  if (runtimeStatus === 'completed') {
+    return 'DONE';
+  }
+  return 'EXIT';
+}
+
+export abstract class BaseAgentStatusReducer implements AgentStatusReducer {
+  abstract readonly agentType: string;
+
+  protected constructor() {}
+
+  project(input: AgentStatusProjectionInput): StreamSessionStatusModel | null {
+    const previous = input.previous;
+    let workText = previous?.lastKnownWork ?? null;
+    let workPhaseHint = previous?.phaseHint ?? null;
+    let workObservedAt = previous?.lastKnownWorkAt ?? null;
+
+    if (input.telemetry !== null && eventIsNewer(input.telemetry.observedAt, workObservedAt)) {
+      const projected = this.projectFromTelemetry(input.telemetry);
+      if (projected !== null) {
+        workText = projected.text;
+        workPhaseHint = projected.phaseHint;
+        workObservedAt = input.telemetry.observedAt;
+      }
+    }
+
+    if (
+      input.runtimeStatus === 'completed' &&
+      eventIsNewer(input.observedAt, workObservedAt) &&
+      workPhaseHint !== 'needs-action'
+    ) {
+      workText = 'inactive';
+      workPhaseHint = 'idle';
+      workObservedAt = input.observedAt;
+    }
+    if (input.runtimeStatus === 'exited' && eventIsNewer(input.observedAt, workObservedAt)) {
+      workText = 'exited';
+      workPhaseHint = 'idle';
+      workObservedAt = input.observedAt;
+    }
+
+    const phase = phaseFromRuntimeStatus(input.runtimeStatus, workPhaseHint);
+    const normalizedAttentionReason = normalizeText(input.attentionReason);
+    const detailText =
+      (input.runtimeStatus === 'needs-input' ? normalizedAttentionReason : null) ??
+      workText ??
+      normalizedAttentionReason ??
+      defaultTextForPhase(phase);
+
+    return {
+      runtimeStatus: input.runtimeStatus,
+      phase,
+      glyph: glyphForPhase(phase),
+      badge: badgeForRuntimeStatus(input.runtimeStatus),
+      detailText,
+      attentionReason: normalizedAttentionReason,
+      lastKnownWork: workText,
+      lastKnownWorkAt: workObservedAt,
+      phaseHint: workPhaseHint,
+      observedAt: input.observedAt,
+    };
+  }
+
+  protected projectFromTelemetry(_telemetry: StreamTelemetrySummary): WorkProjection | null {
+    return null;
+  }
+}

package/src/control-plane/status/reducers/claude-status-reducer.ts

@@ -0,0 +1,37 @@
+import type { StreamTelemetrySummary } from '../../stream-protocol.ts';
+import { BaseAgentStatusReducer } from '../reducer-base.ts';
+
+function normalize(value: string | null): string {
+  return (value ?? '').trim().toLowerCase();
+}
+
+export class ClaudeStatusReducer extends BaseAgentStatusReducer {
+  readonly agentType = 'claude';
+
+  constructor() {
+    super();
+  }
+
+  protected override projectFromTelemetry(
+    telemetry: StreamTelemetrySummary,
+  ): { text: string | null; phaseHint: 'needs-action' | 'working' | 'idle' | null } | null {
+    const eventName = normalize(telemetry.eventName);
+    if (eventName === 'claude.userpromptsubmit' || eventName === 'claude.pretooluse') {
+      return {
+        text: 'active',
+        phaseHint: 'working',
+      };
+    }
+    if (
+      eventName === 'claude.stop' ||
+      eventName === 'claude.subagentstop' ||
+      eventName === 'claude.sessionend'
+    ) {
+      return {
+        text: 'inactive',
+        phaseHint: 'idle',
+      };
+    }
+    return null;
+  }
+}

package/src/control-plane/status/reducers/codex-status-reducer.ts

@@ -0,0 +1,48 @@
+import type { StreamTelemetrySummary } from '../../stream-protocol.ts';
+import { BaseAgentStatusReducer } from '../reducer-base.ts';
+
+function normalize(value: string | null): string {
+  return (value ?? '').trim().toLowerCase();
+}
+
+export class CodexStatusReducer extends BaseAgentStatusReducer {
+  readonly agentType = 'codex';
+
+  constructor() {
+    super();
+  }
+
+  protected override projectFromTelemetry(
+    telemetry: StreamTelemetrySummary,
+  ): { text: string | null; phaseHint: 'needs-action' | 'working' | 'idle' | null } | null {
+    const eventName = normalize(telemetry.eventName);
+    const summary = normalize(telemetry.summary);
+    if (eventName === 'codex.user_prompt') {
+      return {
+        text: 'active',
+        phaseHint: 'working',
+      };
+    }
+    if (eventName === 'codex.turn.e2e_duration_ms') {
+      return {
+        text: 'inactive',
+        phaseHint: 'idle',
+      };
+    }
+    if (eventName === 'codex.sse_event') {
+      if (
+        summary.includes('response.created') ||
+        summary.includes('response.in_progress') ||
+        summary.includes('response.output_text.delta') ||
+        summary.includes('response.output_item.added') ||
+        summary.includes('response.function_call_arguments.delta')
+      ) {
+        return {
+          text: 'active',
+          phaseHint: 'working',
+        };
+      }
+    }
+    return null;
+  }
+}

package/src/control-plane/status/reducers/critique-status-reducer.ts

@@ -0,0 +1,15 @@
+import type { StreamSessionStatusModel } from '../../stream-protocol.ts';
+import type { AgentStatusProjectionInput } from '../agent-status-reducer.ts';
+import { BaseAgentStatusReducer } from '../reducer-base.ts';
+
+export class CritiqueStatusReducer extends BaseAgentStatusReducer {
+  readonly agentType = 'critique';
+
+  constructor() {
+    super();
+  }
+
+  override project(_input: AgentStatusProjectionInput): StreamSessionStatusModel | null {
+    return null;
+  }
+}

package/src/control-plane/status/reducers/cursor-status-reducer.ts

@@ -0,0 +1,37 @@
+import type { StreamTelemetrySummary } from '../../stream-protocol.ts';
+import { BaseAgentStatusReducer } from '../reducer-base.ts';
+
+function normalize(value: string | null): string {
+  return (value ?? '').trim().toLowerCase();
+}
+
+export class CursorStatusReducer extends BaseAgentStatusReducer {
+  readonly agentType = 'cursor';
+
+  constructor() {
+    super();
+  }
+
+  protected override projectFromTelemetry(
+    telemetry: StreamTelemetrySummary,
+  ): { text: string | null; phaseHint: 'needs-action' | 'working' | 'idle' | null } | null {
+    const eventName = normalize(telemetry.eventName);
+    if (
+      eventName === 'cursor.beforesubmitprompt' ||
+      eventName === 'cursor.beforeshellexecution' ||
+      eventName === 'cursor.beforemcptool'
+    ) {
+      return {
+        text: 'active',
+        phaseHint: 'working',
+      };
+    }
+    if (eventName === 'cursor.stop' || eventName === 'cursor.sessionend') {
+      return {
+        text: 'inactive',
+        phaseHint: 'idle',
+      };
+    }
+    return null;
+  }
+}