@jmoyers/harness 0.1.11 → 0.1.20

package/src/control-plane/stream-session-runtime-types.ts

@@ -0,0 +1,41 @@
+import type { CodexLiveEvent } from '../codex/live-session.ts';
+import type { PtyExit } from '../pty/pty_host.ts';
+import type { TerminalBufferTail, TerminalSnapshotFrame } from '../terminal/snapshot-oracle.ts';
+
+export interface SessionDataEvent {
+  cursor: number;
+  chunk: Buffer;
+}
+
+export interface SessionAttachHandlers {
+  onData: (event: SessionDataEvent) => void;
+  onExit: (exit: PtyExit) => void;
+}
+
+export interface LiveSessionLike {
+  attach(handlers: SessionAttachHandlers, sinceCursor?: number): string;
+  detach(attachmentId: string): void;
+  latestCursorValue(): number;
+  processId(): number | null;
+  write(data: string | Uint8Array): void;
+  resize(cols: number, rows: number): void;
+  snapshot(): TerminalSnapshotFrame;
+  bufferTail?(tailLines?: number): TerminalBufferTail;
+  close(): void;
+  onEvent(listener: (event: CodexLiveEvent) => void): () => void;
+}
+
+export interface StartSessionRuntimeInput {
+  readonly sessionId: string;
+  readonly args: readonly string[];
+  readonly initialCols: number;
+  readonly initialRows: number;
+  readonly env?: Record<string, string>;
+  readonly cwd?: string;
+  readonly tenantId?: string;
+  readonly userId?: string;
+  readonly workspaceId?: string;
+  readonly worktreeId?: string;
+  readonly terminalForegroundHex?: string;
+  readonly terminalBackgroundHex?: string;
+}

package/src/{mux/live-mux/control-plane-records.ts → core/contracts/records.ts}

@@ -1,8 +1,12 @@
-import type { StreamSessionController } from '../../control-plane/stream-protocol.ts';
-import type { StreamSessionStatusModel } from '../../control-plane/stream-protocol.ts';
-import type { ConversationRailSessionSummary } from '../conversation-rail.ts';
-
-interface ControlPlaneDirectoryRecord {
+import {
+  isStreamSessionRuntimeStatus,
+  parseStreamSessionStatusModel,
+  type StreamSessionController,
+  type StreamSessionRuntimeStatus,
+  type StreamSessionStatusModel,
+} from '../../control-plane/stream-protocol.ts';
+
+export interface ControlPlaneDirectoryRecord {
   readonly directoryId: string;
   readonly tenantId: string;
   readonly userId: string;
@@ -12,7 +16,7 @@ interface ControlPlaneDirectoryRecord {
   readonly archivedAt: string | null;
 }
 
-interface ControlPlaneConversationRecord {
+export interface ControlPlaneConversationRecord {
   readonly conversationId: string;
   readonly directoryId: string;
   readonly tenantId: string;
@@ -21,12 +25,12 @@ interface ControlPlaneConversationRecord {
   readonly title: string;
   readonly agentType: string;
   readonly adapterState: Record<string, unknown>;
-  readonly runtimeStatus: ConversationRailSessionSummary['status'];
+  readonly runtimeStatus: StreamSessionRuntimeStatus;
   readonly runtimeStatusModel: StreamSessionStatusModel | null;
   readonly runtimeLive: boolean;
 }
 
-interface ControlPlaneRepositoryRecord {
+export interface ControlPlaneRepositoryRecord {
   readonly repositoryId: string;
   readonly tenantId: string;
   readonly userId: string;
@@ -39,14 +43,14 @@ interface ControlPlaneRepositoryRecord {
   readonly archivedAt: string | null;
 }
 
-interface ControlPlaneGitSummaryRecord {
+export interface ControlPlaneGitSummaryRecord {
   readonly branch: string;
   readonly changedFiles: number;
   readonly additions: number;
   readonly deletions: number;
 }
 
-interface ControlPlaneGitRepositorySnapshotRecord {
+export interface ControlPlaneGitRepositorySnapshotRecord {
   readonly normalizedRemoteUrl: string | null;
   readonly commitCount: number | null;
   readonly lastCommitAt: string | null;
@@ -55,7 +59,7 @@ interface ControlPlaneGitRepositorySnapshotRecord {
   readonly defaultBranch: string | null;
 }
 
-interface ControlPlaneDirectoryGitStatusRecord {
+export interface ControlPlaneDirectoryGitStatusRecord {
   readonly directoryId: string;
   readonly summary: ControlPlaneGitSummaryRecord;
   readonly repositorySnapshot: ControlPlaneGitRepositorySnapshotRecord;
@@ -64,10 +68,10 @@ interface ControlPlaneDirectoryGitStatusRecord {
   readonly observedAt: string;
 }
 
-type TaskStatus = 'draft' | 'ready' | 'in-progress' | 'completed';
-type TaskScopeKind = 'global' | 'repository' | 'project';
+export type TaskStatus = 'draft' | 'ready' | 'in-progress' | 'completed';
+export type TaskScopeKind = 'global' | 'repository' | 'project';
 
-interface ControlPlaneTaskRecord {
+export interface ControlPlaneTaskRecord {
   readonly taskId: string;
   readonly tenantId: string;
   readonly userId: string;
@@ -76,7 +80,7 @@ interface ControlPlaneTaskRecord {
   readonly scopeKind: TaskScopeKind;
   readonly projectId: string | null;
   readonly title: string;
-  readonly description: string;
+  readonly body: string;
   readonly status: TaskStatus;
   readonly orderIndex: number;
   readonly claimedByControllerId: string | null;
@@ -123,78 +127,6 @@ function asObjectRecord(value: unknown): Record<string, unknown> | null {
   return value as Record<string, unknown>;
 }
 
-function parseRuntimeStatusModel(value: unknown): StreamSessionStatusModel | null | undefined {
-  if (value === null) {
-    return null;
-  }
-  const model = asObjectRecord(value);
-  if (model === null) {
-    return undefined;
-  }
-  const runtimeStatus = model['runtimeStatus'];
-  const phase = model['phase'];
-  const glyph = model['glyph'];
-  const badge = model['badge'];
-  const detailText = asRequiredString(model['detailText']);
-  const attentionReason = asNullableString(model['attentionReason']);
-  const lastKnownWork = asNullableString(model['lastKnownWork']);
-  const lastKnownWorkAt = asNullableString(model['lastKnownWorkAt']);
-  const phaseHint = model['phaseHint'];
-  const observedAt = asRequiredString(model['observedAt']);
-  if (
-    detailText === null ||
-    attentionReason === undefined ||
-    lastKnownWork === undefined ||
-    lastKnownWorkAt === undefined ||
-    observedAt === null
-  ) {
-    return undefined;
-  }
-  if (
-    runtimeStatus !== 'running' &&
-    runtimeStatus !== 'needs-input' &&
-    runtimeStatus !== 'completed' &&
-    runtimeStatus !== 'exited'
-  ) {
-    return undefined;
-  }
-  if (
-    phase !== 'needs-action' &&
-    phase !== 'starting' &&
-    phase !== 'working' &&
-    phase !== 'idle' &&
-    phase !== 'exited'
-  ) {
-    return undefined;
-  }
-  if (glyph !== '▲' && glyph !== '◔' && glyph !== '◆' && glyph !== '○' && glyph !== '■') {
-    return undefined;
-  }
-  if (badge !== 'NEED' && badge !== 'RUN ' && badge !== 'DONE' && badge !== 'EXIT') {
-    return undefined;
-  }
-  if (
-    phaseHint !== null &&
-    phaseHint !== 'needs-action' &&
-    phaseHint !== 'working' &&
-    phaseHint !== 'idle'
-  ) {
-    return undefined;
-  }
-  return {
-    runtimeStatus,
-    phase,
-    glyph,
-    badge,
-    detailText,
-    attentionReason,
-    lastKnownWork,
-    lastKnownWorkAt,
-    phaseHint,
-    observedAt,
-  };
-}
-
 export function parseDirectoryRecord(value: unknown): ControlPlaneDirectoryRecord | null {
   const record = asRecord(value);
   if (record === null) {
@@ -247,7 +179,7 @@ export function parseConversationRecord(value: unknown): ControlPlaneConversatio
   const agentType = asRequiredString(record['agentType']);
   const adapterState = asObjectRecord(record['adapterState']);
   const runtimeStatus = record['runtimeStatus'];
-  const runtimeStatusModel = parseRuntimeStatusModel(record['runtimeStatusModel']);
+  const runtimeStatusModel = parseStreamSessionStatusModel(record['runtimeStatusModel']);
   const runtimeLive = record['runtimeLive'];
 
   if (
@@ -265,12 +197,7 @@ export function parseConversationRecord(value: unknown): ControlPlaneConversatio
     return null;
   }
 
-  if (
-    runtimeStatus !== 'running' &&
-    runtimeStatus !== 'needs-input' &&
-    runtimeStatus !== 'completed' &&
-    runtimeStatus !== 'exited'
-  ) {
+  if (!isStreamSessionRuntimeStatus(runtimeStatus)) {
     return null;
   }
 
@@ -457,7 +384,7 @@ export function parseTaskRecord(value: unknown): ControlPlaneTaskRecord | null {
   const repositoryId = asOptionalString(record['repositoryId']);
   const projectId = asOptionalString(record['projectId']);
   const title = asRequiredString(record['title']);
-  const description = asRequiredString(record['description']);
+  const body = asRequiredString(record['body'] ?? record['description']);
   const status = parseTaskStatus(record['status']);
   const scopeKind = parseTaskScopeKind(record['scopeKind'], repositoryId, projectId);
   const orderIndex = record['orderIndex'];
@@ -479,7 +406,7 @@ export function parseTaskRecord(value: unknown): ControlPlaneTaskRecord | null {
     projectId === undefined ||
     scopeKind === null ||
     title === null ||
-    description === null ||
+    body === null ||
     status === null ||
     typeof orderIndex !== 'number' ||
     claimedByControllerId === undefined ||
@@ -503,7 +430,7 @@ export function parseTaskRecord(value: unknown): ControlPlaneTaskRecord | null {
     scopeKind,
     projectId,
     title,
-    description,
+    body,
     status,
     orderIndex,
     claimedByControllerId,

package/src/core/state/observed-stream-cursor.ts

@@ -0,0 +1,43 @@
+export interface ObservedStreamCursorState {
+  readonly lastCursorBySubscriptionId: ReadonlyMap<string, number>;
+}
+
+interface ObserveStreamCursorInput {
+  readonly subscriptionId: string;
+  readonly cursor: number;
+}
+
+interface ObserveStreamCursorResult {
+  readonly accepted: boolean;
+  readonly previousCursor: number | null;
+  readonly state: ObservedStreamCursorState;
+}
+
+export function createObservedStreamCursorState(): ObservedStreamCursorState {
+  return {
+    lastCursorBySubscriptionId: new Map<string, number>(),
+  };
+}
+
+export function observeStreamCursor(
+  state: ObservedStreamCursorState,
+  input: ObserveStreamCursorInput,
+): ObserveStreamCursorResult {
+  const previousCursor = state.lastCursorBySubscriptionId.get(input.subscriptionId) ?? null;
+  if (previousCursor !== null && input.cursor <= previousCursor) {
+    return {
+      accepted: false,
+      previousCursor,
+      state,
+    };
+  }
+  const next = new Map(state.lastCursorBySubscriptionId);
+  next.set(input.subscriptionId, input.cursor);
+  return {
+    accepted: true,
+    previousCursor,
+    state: {
+      lastCursorBySubscriptionId: next,
+    },
+  };
+}

package/src/core/state/synced-observed-state.ts

@@ -0,0 +1,273 @@
+import type { StreamObservedEvent } from '../../control-plane/stream-protocol.ts';
+import {
+  parseConversationRecord,
+  parseDirectoryRecord,
+  parseRepositoryRecord,
+  parseTaskRecord,
+  type ControlPlaneConversationRecord,
+  type ControlPlaneDirectoryRecord,
+  type ControlPlaneRepositoryRecord,
+  type ControlPlaneTaskRecord,
+} from '../contracts/records.ts';
+
+export interface HarnessSyncedState {
+  readonly directoriesById: Readonly<Record<string, ControlPlaneDirectoryRecord>>;
+  readonly conversationsById: Readonly<Record<string, ControlPlaneConversationRecord>>;
+  readonly repositoriesById: Readonly<Record<string, ControlPlaneRepositoryRecord>>;
+  readonly tasksById: Readonly<Record<string, ControlPlaneTaskRecord>>;
+}
+
+export interface HarnessSyncedObservedReduction {
+  readonly state: HarnessSyncedState;
+  readonly changed: boolean;
+  readonly removedConversationIds: readonly string[];
+  readonly removedDirectoryIds: readonly string[];
+  readonly removedTaskIds: readonly string[];
+  readonly upsertedDirectoryIds: readonly string[];
+  readonly upsertedConversationIds: readonly string[];
+  readonly upsertedRepositoryIds: readonly string[];
+  readonly upsertedTaskIds: readonly string[];
+}
+
+const EMPTY_IDS: readonly string[] = [];
+
+export function createHarnessSyncedState(): HarnessSyncedState {
+  return {
+    directoriesById: {},
+    conversationsById: {},
+    repositoriesById: {},
+    tasksById: {},
+  };
+}
+
+function unchanged(state: HarnessSyncedState): HarnessSyncedObservedReduction {
+  return {
+    state,
+    changed: false,
+    removedConversationIds: EMPTY_IDS,
+    removedDirectoryIds: EMPTY_IDS,
+    removedTaskIds: EMPTY_IDS,
+    upsertedDirectoryIds: EMPTY_IDS,
+    upsertedConversationIds: EMPTY_IDS,
+    upsertedRepositoryIds: EMPTY_IDS,
+    upsertedTaskIds: EMPTY_IDS,
+  };
+}
+
+export function applyObservedEventToSyncedState(
+  state: HarnessSyncedState,
+  event: StreamObservedEvent,
+): HarnessSyncedObservedReduction {
+  if (event.type === 'directory-upserted') {
+    const directory = parseDirectoryRecord(event.directory);
+    if (directory === null) {
+      return unchanged(state);
+    }
+    return {
+      ...unchanged(state),
+      state: {
+        ...state,
+        directoriesById: {
+          ...state.directoriesById,
+          [directory.directoryId]: directory,
+        },
+      },
+      changed: true,
+      upsertedDirectoryIds: [directory.directoryId],
+    };
+  }
+
+  if (event.type === 'directory-archived') {
+    const removedConversationIds: string[] = [];
+    const nextConversations = { ...state.conversationsById };
+    for (const [conversationId, conversation] of Object.entries(state.conversationsById)) {
+      if (conversation.directoryId !== event.directoryId) {
+        continue;
+      }
+      delete nextConversations[conversationId];
+      removedConversationIds.push(conversationId);
+    }
+    const directoryExisted = state.directoriesById[event.directoryId] !== undefined;
+    if (!directoryExisted && removedConversationIds.length === 0) {
+      return unchanged(state);
+    }
+    const nextDirectories = { ...state.directoriesById };
+    delete nextDirectories[event.directoryId];
+    return {
+      ...unchanged(state),
+      state: {
+        ...state,
+        directoriesById: nextDirectories,
+        conversationsById: nextConversations,
+      },
+      changed: true,
+      removedConversationIds,
+      removedDirectoryIds: directoryExisted ? [event.directoryId] : EMPTY_IDS,
+    };
+  }
+
+  if (event.type === 'conversation-created' || event.type === 'conversation-updated') {
+    const conversation = parseConversationRecord(event.conversation);
+    if (conversation === null) {
+      return unchanged(state);
+    }
+    return {
+      ...unchanged(state),
+      state: {
+        ...state,
+        conversationsById: {
+          ...state.conversationsById,
+          [conversation.conversationId]: conversation,
+        },
+      },
+      changed: true,
+      upsertedConversationIds: [conversation.conversationId],
+    };
+  }
+
+  if (event.type === 'conversation-archived' || event.type === 'conversation-deleted') {
+    if (state.conversationsById[event.conversationId] === undefined) {
+      return unchanged(state);
+    }
+    const nextConversations = { ...state.conversationsById };
+    delete nextConversations[event.conversationId];
+    return {
+      ...unchanged(state),
+      state: {
+        ...state,
+        conversationsById: nextConversations,
+      },
+      changed: true,
+      removedConversationIds: [event.conversationId],
+    };
+  }
+
+  if (event.type === 'repository-upserted' || event.type === 'repository-updated') {
+    const repository = parseRepositoryRecord(event.repository);
+    if (repository === null) {
+      return unchanged(state);
+    }
+    return {
+      ...unchanged(state),
+      state: {
+        ...state,
+        repositoriesById: {
+          ...state.repositoriesById,
+          [repository.repositoryId]: repository,
+        },
+      },
+      changed: true,
+      upsertedRepositoryIds: [repository.repositoryId],
+    };
+  }
+
+  if (event.type === 'repository-archived') {
+    const existing = state.repositoriesById[event.repositoryId];
+    if (existing === undefined) {
+      return unchanged(state);
+    }
+    return {
+      ...unchanged(state),
+      state: {
+        ...state,
+        repositoriesById: {
+          ...state.repositoriesById,
+          [event.repositoryId]: {
+            ...existing,
+            archivedAt: event.ts,
+          },
+        },
+      },
+      changed: true,
+      upsertedRepositoryIds: [event.repositoryId],
+    };
+  }
+
+  if (event.type === 'task-created' || event.type === 'task-updated') {
+    const task = parseTaskRecord(event.task);
+    if (task === null) {
+      return unchanged(state);
+    }
+    return {
+      ...unchanged(state),
+      state: {
+        ...state,
+        tasksById: {
+          ...state.tasksById,
+          [task.taskId]: task,
+        },
+      },
+      changed: true,
+      upsertedTaskIds: [task.taskId],
+    };
+  }
+
+  if (event.type === 'task-deleted') {
+    if (state.tasksById[event.taskId] === undefined) {
+      return unchanged(state);
+    }
+    const nextTasks = { ...state.tasksById };
+    delete nextTasks[event.taskId];
+    return {
+      ...unchanged(state),
+      state: {
+        ...state,
+        tasksById: nextTasks,
+      },
+      changed: true,
+      removedTaskIds: [event.taskId],
+    };
+  }
+
+  if (event.type === 'task-reordered') {
+    const nextTasks = { ...state.tasksById };
+    const upsertedTaskIds: string[] = [];
+    for (const value of event.tasks) {
+      const task = parseTaskRecord(value);
+      if (task === null) {
+        continue;
+      }
+      nextTasks[task.taskId] = task;
+      upsertedTaskIds.push(task.taskId);
+    }
+    if (upsertedTaskIds.length === 0) {
+      return unchanged(state);
+    }
+    return {
+      ...unchanged(state),
+      state: {
+        ...state,
+        tasksById: nextTasks,
+      },
+      changed: true,
+      upsertedTaskIds,
+    };
+  }
+
+  if (event.type === 'session-status') {
+    const conversationId = event.conversationId ?? event.sessionId;
+    const existing = state.conversationsById[conversationId];
+    if (existing === undefined) {
+      return unchanged(state);
+    }
+    return {
+      ...unchanged(state),
+      state: {
+        ...state,
+        conversationsById: {
+          ...state.conversationsById,
+          [conversationId]: {
+            ...existing,
+            runtimeStatus: event.status,
+            runtimeStatusModel: event.statusModel,
+            runtimeLive: event.live,
+          },
+        },
+      },
+      changed: true,
+      upsertedConversationIds: [conversationId],
+    };
+  }
+
+  return unchanged(state);
+}

package/src/core/store/harness-synced-store.ts

@@ -0,0 +1,81 @@
+import { createStore, type StoreApi } from 'zustand/vanilla';
+import type { StreamObservedEvent } from '../../control-plane/stream-protocol.ts';
+import {
+  createObservedStreamCursorState,
+  observeStreamCursor,
+  type ObservedStreamCursorState,
+} from '../state/observed-stream-cursor.ts';
+import {
+  applyObservedEventToSyncedState,
+  createHarnessSyncedState,
+  type HarnessSyncedObservedReduction,
+  type HarnessSyncedState,
+} from '../state/synced-observed-state.ts';
+
+export interface HarnessSyncedStoreState {
+  readonly synced: HarnessSyncedState;
+  readonly observedStreamCursor: ObservedStreamCursorState;
+}
+
+export interface HarnessSyncedStoreApplyInput {
+  readonly subscriptionId: string;
+  readonly cursor: number;
+  readonly event: StreamObservedEvent;
+}
+
+export interface HarnessSyncedStoreApplyResult extends HarnessSyncedObservedReduction {
+  readonly cursorAccepted: boolean;
+  readonly previousCursor: number | null;
+  readonly previousState: HarnessSyncedState;
+}
+
+export type HarnessSyncedStore = StoreApi<HarnessSyncedStoreState>;
+
+export function createHarnessSyncedStore(
+  initial: Partial<HarnessSyncedStoreState> = {},
+): HarnessSyncedStore {
+  return createStore<HarnessSyncedStoreState>(() => ({
+    synced: initial.synced ?? createHarnessSyncedState(),
+    observedStreamCursor: initial.observedStreamCursor ?? createObservedStreamCursorState(),
+  }));
+}
+
+export function applyObservedEventToHarnessSyncedStore(
+  store: HarnessSyncedStore,
+  input: HarnessSyncedStoreApplyInput,
+): HarnessSyncedStoreApplyResult {
+  const state = store.getState();
+  const observedCursor = observeStreamCursor(state.observedStreamCursor, {
+    subscriptionId: input.subscriptionId,
+    cursor: input.cursor,
+  });
+
+  if (!observedCursor.accepted) {
+    return {
+      state: state.synced,
+      changed: false,
+      cursorAccepted: false,
+      previousCursor: observedCursor.previousCursor,
+      previousState: state.synced,
+      removedConversationIds: [],
+      removedDirectoryIds: [],
+      removedTaskIds: [],
+      upsertedDirectoryIds: [],
+      upsertedConversationIds: [],
+      upsertedRepositoryIds: [],
+      upsertedTaskIds: [],
+    };
+  }
+
+  const reduced = applyObservedEventToSyncedState(state.synced, input.event);
+  store.setState({
+    observedStreamCursor: observedCursor.state,
+    synced: reduced.state,
+  });
+  return {
+    ...reduced,
+    cursorAccepted: true,
+    previousCursor: observedCursor.previousCursor,
+    previousState: state.synced,
+  };
+}