ompchamber 3.0.0 → 3.1.0

package/src/server/routes/omp/session-todos.ts

@@ -0,0 +1,80 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * GET /api/omp/session-todos?sessionId=<uuid> — the session's live todo list.
+ *
+ * Read-only projection of oh-my-pi's own persisted `todo` state: the deepest
+ * committed snapshot on the session transcript's active branch. omp is the
+ * owner of this list and there is no second copy — see
+ * `@/server/lib/omp/session/todos`.
+ *
+ * MOCK mode answers a deterministic demo list so the right-panel view renders
+ * its full range of states (in progress, blocked, completed, abandoned) without
+ * an omp install.
+ */
+
+import { json, NO_STORE_HEADERS } from '@/server/lib/remix-compat';
+import type { LoaderFunctionArgs } from '@/server/lib/remix-compat';
+import { isMockMode } from '@/server/mock.server';
+import { readSessionTodos } from '@/server/lib/omp/session/todos';
+import { todoProgress } from '@/shared/lib/chat/todo/snapshot';
+import type { SessionTodosPayload, TodoPhase } from '@/shared/types/todo';
+
+/** Demo list under MOCK=true: one phase of every status the panel must draw. */
+const MOCK_PHASES: TodoPhase[] = [
+  {
+    name: 'Server data',
+    tasks: [
+      { content: 'Read the session transcript for the deepest todo snapshot', status: 'completed' },
+      { content: 'Serve the list over /api/omp/session-todos', status: 'in_progress' },
+      { content: 'Cache the parse by size + mtime', status: 'pending' },
+      { content: 'Wire the panel poll to omp:session-updated', status: 'blocked', blocker: 'waiting on the event name' },
+    ],
+  },
+  {
+    name: 'Panel',
+    tasks: [
+      { content: 'Draw phase groups with per-status glyphs', status: 'pending' },
+      { content: 'Collapse closed tasks behind a toggle', status: 'abandoned' },
+    ],
+  },
+];
+
+export async function loader({ request }: LoaderFunctionArgs) {
+  const url = new URL(request.url);
+  const sessionId = url.searchParams.get('sessionId');
+
+  if (isMockMode()) {
+    return json(
+      {
+        sessionId: sessionId ?? 'mock',
+        snapshot: {
+          phases: MOCK_PHASES,
+          sourceEntryId: 'mock-entry',
+          source: 'toolResult',
+          updatedAt: new Date().toISOString(),
+          op: 'start',
+          storage: 'session',
+        },
+        progress: todoProgress(MOCK_PHASES),
+        generatedAt: new Date().toISOString(),
+        isMock: true,
+      } satisfies SessionTodosPayload,
+      { headers: NO_STORE_HEADERS },
+    );
+  }
+
+  if (!sessionId) return json({ error: 'sessionId is required' }, { status: 400 });
+
+  const state = await readSessionTodos(sessionId);
+  const payload: SessionTodosPayload = {
+    sessionId,
+    ...state,
+    generatedAt: new Date().toISOString(),
+    isMock: false,
+  };
+  return json(payload, { headers: NO_STORE_HEADERS });
+}

package/src/shared/lib/chat/{todo-parser.ts → todo/parser.ts}

@@ -1,3 +1,20 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Renderer-side parser for one `todo` tool call: reads the human-readable
+ * checklist omp returns as the tool's text output (and the `list` argument as a
+ * fallback) into phase groups for the chat timeline's tool card.
+ *
+ * This is NOT the authoritative list — a tool card shows what that ONE call
+ * did, while the session's live list is the deepest committed snapshot on the
+ * active branch (`./snapshot.ts`, surfaced by the right-panel Todo view). The
+ * two must not be merged: a card that displayed the session-wide list would
+ * attribute every other call's work to this one.
+ */
+
 import type { ToolCallData } from '@/shared/types';
 
 export interface ParsedTask {

package/src/shared/lib/chat/todo/progress.ts

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Display-side helpers for a todo list: the one-line progress summary, the
+ * per-task visual state, and the "which task is the agent on" lookup the panel
+ * highlights.
+ *
+ * Everything here is presentational — the parse itself lives in `snapshot.ts`.
+ * The status → presentation mapping is a table rather than a chain of `if`s
+ * because there are five statuses and three consumers (icon, label, class
+ * list), and a missing case in any one of them is how a `blocked` task ends up
+ * rendered as a plain pending one.
+ */
+
+import type { TodoItem, TodoPhase, TodoProgress, TodoStatus } from '@/shared/types/todo';
+
+export interface TodoStatusVisual {
+  /** Short label for the row's status pill. */
+  label: string;
+  /** Tailwind text color for the icon and label. */
+  tone: string;
+  /** True when the row is a live (in-progress) task — highlighted, not dimmed. */
+  active: boolean;
+  /** True when the task is out of the way (completed / abandoned). */
+  closed: boolean;
+}
+
+const STATUS_VISUALS: Record<TodoStatus, TodoStatusVisual> = {
+  pending: { label: 'Pending', tone: 'text-ink/45', active: false, closed: false },
+  in_progress: { label: 'In progress', tone: 'text-ink', active: true, closed: false },
+  completed: { label: 'Completed', tone: 'text-success', active: false, closed: true },
+  abandoned: { label: 'Abandoned', tone: 'text-error/70', active: false, closed: true },
+  blocked: { label: 'Blocked', tone: 'text-warning', active: false, closed: false },
+};
+
+export function todoStatusVisual(status: TodoStatus): TodoStatusVisual {
+  return STATUS_VISUALS[status] ?? STATUS_VISUALS.pending;
+}
+
+/**
+ * One-line summary of a snapshot: `4/11 done · 1 in progress · 2 blocked`.
+ *
+ * Counts CLOSED (completed + abandoned) against the total, matching omp's own
+ * HUD counter — an abandoned task is deliberately not coming back, so leaving
+ * it in the denominator is what makes a list read as permanently stuck.
+ */
+export function todoProgressLabel(progress: TodoProgress): string {
+  if (progress.total === 0) return 'No tasks';
+  const parts = [`${progress.closed}/${progress.total} done`];
+  if (progress.inProgress > 0) parts.push(`${progress.inProgress} in progress`);
+  if (progress.blocked > 0) parts.push(`${progress.blocked} blocked`);
+  if (progress.abandoned > 0) parts.push(`${progress.abandoned} abandoned`);
+  return parts.join(' · ');
+}
+
+/** Percentage of the list that is closed, rounded to a whole number. */
+export function todoProgressPercent(progress: TodoProgress): number {
+  if (progress.total === 0) return 0;
+  return Math.round((progress.closed / progress.total) * 100);
+}
+
+/**
+ * The row the panel marks as current: the in-progress task, else the first
+ * pending one. Identified by phase index + task index rather than by content,
+ * because two phases may legitimately hold tasks with identical text (omp
+ * itself keys its own task lookup by content, and that ambiguity is its
+ * problem, not one to inherit here).
+ */
+export function currentTaskLocation(phases: readonly TodoPhase[]): { phase: number; task: number } | null {
+  for (let phase = 0; phase < phases.length; phase++) {
+    const tasks = phases[phase].tasks;
+    for (let task = 0; task < tasks.length; task++) {
+      if (tasks[task].status === 'in_progress') return { phase, task };
+    }
+  }
+  for (let phase = 0; phase < phases.length; phase++) {
+    const tasks = phases[phase].tasks;
+    for (let task = 0; task < tasks.length; task++) {
+      if (tasks[task].status === 'pending') return { phase, task };
+    }
+  }
+  return null;
+}
+
+/** Tasks of one phase that are closed, for the phase header's `n/m` badge. */
+export function closedTaskCount(phase: TodoPhase): number {
+  return phase.tasks.filter((task) => task.status === 'completed' || task.status === 'abandoned').length;
+}
+
+/** Blocker note of a task, trimmed, or undefined when there is nothing to show. */
+export function taskNote(task: TodoItem): string | undefined {
+  const note = task.blocker?.trim() || task.details?.trim();
+  return note ? note : undefined;
+}

package/src/shared/lib/chat/todo/snapshot.test.ts

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { latestTodoSnapshot, todoProgress } from '@/shared/lib/chat/todo/snapshot';
+import type { TodoPhase, TodoStatus } from '@/shared/types/todo';
+
+/**
+ * The reader has to match oh-my-pi's own branch rehydration, and every rule it
+ * implements was verified against a real session written by omp 18.3.0:
+ *
+ *   - a `todo` toolResult carries `message.details.phases`;
+ *   - `op:"view"` results carry phases but commit nothing (omp skips them);
+ *   - a `user_todo_edit` custom entry carries `data.phases` and is durable;
+ *   - the list is read off the ACTIVE BRANCH (leaf → root via `parentId`), so a
+ *     rewound fork must not resurface.
+ *
+ * The failure mode of getting any of these wrong is a panel that quietly shows
+ * a stale plan, which no other surface would contradict.
+ */
+
+const phases = (...tasks: Array<[string, TodoStatus]>): TodoPhase[] => [
+  { name: 'Phase', tasks: tasks.map(([content, status]) => ({ content, status })) },
+];
+
+function entry(id: string, parentId: string | null, body: Record<string, unknown>) {
+  return { id, parentId, timestamp: '2026-09-25T00:00:00.000Z', ...body };
+}
+
+function todoResult(id: string, parentId: string | null, details: Record<string, unknown>) {
+  return entry(id, parentId, {
+    type: 'message',
+    message: { role: 'toolResult', toolName: 'todo', content: [{ type: 'text', text: '' }], details },
+  });
+}
+
+describe('latestTodoSnapshot', () => {
+  test('reads the deepest committed snapshot on the active branch', () => {
+    const entries = [
+      todoResult('a1', null, { op: 'init', phases: phases(['one', 'pending'], ['two', 'pending']) }),
+      todoResult('a2', 'a1', { op: 'done', phases: phases(['one', 'completed'], ['two', 'in_progress']) }),
+    ];
+
+    const snapshot = latestTodoSnapshot(entries);
+
+    expect(snapshot?.sourceEntryId).toBe('a2');
+    expect(snapshot?.source).toBe('toolResult');
+    expect(snapshot?.op).toBe('done');
+    expect(snapshot?.phases[0].tasks[0].status).toBe('completed');
+  });
+
+  test('skips a `view` result — it reports the list without committing it', () => {
+    const entries = [
+      todoResult('a1', null, { op: 'init', phases: phases(['one', 'completed']) }),
+      // A view result can be arbitrarily stale (it is echoed, not committed).
+      todoResult('a2', 'a1', { op: 'view', phases: phases(['one', 'pending']) }),
+    ];
+
+    expect(latestTodoSnapshot(entries)?.sourceEntryId).toBe('a1');
+  });
+
+  test('skips an errored result', () => {
+    const entries = [
+      todoResult('a1', null, { op: 'init', phases: phases(['one', 'pending']) }),
+      {
+        ...todoResult('a2', 'a1', { op: 'done', phases: phases(['one', 'completed']) }),
+        message: {
+          role: 'toolResult',
+          toolName: 'todo',
+          isError: true,
+          details: { op: 'done', phases: phases(['one', 'completed']) },
+        },
+      },
+    ];
+
+    expect(latestTodoSnapshot(entries)?.sourceEntryId).toBe('a1');
+  });
+
+  test('a `user_todo_edit` custom entry outranks an older tool result', () => {
+    const entries = [
+      todoResult('a1', null, { op: 'init', phases: phases(['one', 'pending']) }),
+      entry('a2', 'a1', {
+        type: 'custom',
+        customType: 'user_todo_edit',
+        data: { phases: phases(['one', 'abandoned']) },
+      }),
+    ];
+
+    const snapshot = latestTodoSnapshot(entries);
+
+    expect(snapshot?.source).toBe('custom');
+    expect(snapshot?.phases[0].tasks[0].status).toBe('abandoned');
+  });
+
+  test('a snapshot on an abandoned branch is ignored (rewind)', () => {
+    // a2 was rewound past: the leaf is b2, whose parent chain never reaches a2.
+    const entries = [
+      todoResult('a1', null, { op: 'init', phases: phases(['old', 'in_progress']) }),
+      todoResult('a2', 'a1', { op: 'done', phases: phases(['old', 'completed']) }),
+      todoResult('b1', 'a1', { op: 'append', phases: phases(['new', 'pending']) }),
+      todoResult('b2', 'b1', { op: 'start', phases: phases(['new', 'in_progress']) }),
+    ];
+
+    const snapshot = latestTodoSnapshot(entries);
+
+    expect(snapshot?.sourceEntryId).toBe('b2');
+    expect(snapshot?.phases[0].tasks[0].content).toBe('new');
+  });
+
+  test('returns null when the transcript holds no todo state', () => {
+    const entries = [
+      entry('a1', null, { type: 'message', message: { role: 'user', content: 'hello' } }),
+      todoResult('a2', 'a1', { op: 'view', phases: phases(['one', 'pending']) }),
+    ];
+
+    expect(latestTodoSnapshot(entries)).toBeNull();
+  });
+
+  test('rejects a malformed snapshot rather than rendering a half list', () => {
+    const entries = [
+      todoResult('a1', null, { op: 'init', phases: [{ name: 'Phase', tasks: [{ content: 'x', status: 'nonsense' }] }] }),
+    ];
+
+    expect(latestTodoSnapshot(entries)).toBeNull();
+  });
+
+  test('carries storage and timestamp when the entry records them', () => {
+    const entries = [todoResult('a1', null, { op: 'init', phases: phases(['one', 'pending']), storage: 'memory' })];
+
+    const snapshot = latestTodoSnapshot(entries);
+
+    expect(snapshot?.storage).toBe('memory');
+    expect(snapshot?.updatedAt).toBe('2026-09-25T00:00:00.000Z');
+  });
+});
+
+describe('todoProgress', () => {
+  test('counts closed as completed plus abandoned', () => {
+    const progress = todoProgress(
+      phases(['a', 'completed'], ['b', 'abandoned'], ['c', 'in_progress'], ['d', 'blocked'], ['e', 'pending']),
+    );
+
+    expect(progress).toEqual({
+      total: 5,
+      completed: 1,
+      closed: 2,
+      inProgress: 1,
+      pending: 1,
+      blocked: 1,
+      abandoned: 1,
+    });
+  });
+});

package/src/shared/lib/chat/todo/snapshot.ts

@@ -0,0 +1,215 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Parse oh-my-pi's persisted `todo` state out of a session transcript.
+ *
+ * omp keeps the authoritative list in its own session file, not in an
+ * in-memory HUD: the `todo` tool commits a snapshot to the entry it appends,
+ * and omp reads the deepest snapshot back off the ACTIVE BRANCH when it
+ * rehydrates (`getLatestTodoPhasesFromEntries` → `syncTodoPhasesFromBranch`).
+ * This module performs the same read, so the chamber's panel shows what the
+ * agent itself would resume with.
+ *
+ * Two rules are load-bearing and each was verified against omp 18.3.0:
+ *
+ *   - **The active branch, not file order.** A session file is a tree: every
+ *     entry carries `parentId`, and a rewind/fork leaves entries on the file
+ *     that the current leaf no longer descends from. omp reads `getBranch()`
+ *     (leaf → root), so file order would resurrect a todo list the agent had
+ *     already rewound past.
+ *   - **A `view` snapshot is not a snapshot.** `todo op=view` returns the
+ *     current list without committing it; a `view` result's phases may be
+ *     stale, so omp skips those results entirely and so does this reader.
+ *     Errored results are skipped for the same reason.
+ */
+
+import { isRecord } from '@/shared/lib/util/guards';
+import type {
+  TodoItem,
+  TodoOperation,
+  TodoPhase,
+  TodoProgress,
+  TodoSnapshot,
+} from '@/shared/types/todo';
+
+const TODO_STATUSES: Record<string, true> = {
+  pending: true,
+  in_progress: true,
+  completed: true,
+  abandoned: true,
+  blocked: true,
+};
+
+/** Custom-entry type omp writes for a durable, non-tool todo mutation. */
+const USER_TODO_EDIT_CUSTOM_TYPE = 'user_todo_edit';
+
+/** Whether an unknown value is one omp-persisted phase. */
+export function isTodoPhase(value: unknown): value is TodoPhase {
+  if (!isRecord(value) || typeof value.name !== 'string' || !Array.isArray(value.tasks)) return false;
+  return value.tasks.every((task) => {
+    if (!isRecord(task) || typeof task.content !== 'string') return false;
+    return typeof task.status === 'string' && TODO_STATUSES[task.status] === true;
+  });
+}
+
+/** Narrow an unknown array to a validated phase list, or undefined. */
+function toPhases(value: unknown): TodoPhase[] | undefined {
+  if (!Array.isArray(value) || !value.every(isTodoPhase)) return undefined;
+  return value as TodoPhase[];
+}
+
+/** One JSONL entry as this reader needs it. */
+interface TodoEntryLike {
+  id?: unknown;
+  parentId?: unknown;
+  timestamp?: unknown;
+  type?: unknown;
+  customType?: unknown;
+  data?: unknown;
+  message?: unknown;
+}
+
+/**
+ * The phases an entry commits, or undefined when it commits none.
+ *
+ * Mirrors omp's own `aVn`: a `user_todo_edit` custom entry carries `data.phases`
+ * (already-normalized), and a `todo` toolResult carries `details.phases` unless
+ * it errored or was a pure `view` read.
+ */
+function committedPhases(entry: TodoEntryLike): TodoPhase[] | undefined {
+  if (entry.type === 'custom' && entry.customType === USER_TODO_EDIT_CUSTOM_TYPE) {
+    const data = isRecord(entry.data) ? entry.data : undefined;
+    return toPhases(data?.phases);
+  }
+  if (entry.type !== 'message') return undefined;
+  const message = isRecord(entry.message) ? entry.message : undefined;
+  if (!message || message.role !== 'toolResult' || message.toolName !== 'todo') return undefined;
+  if (message.isError === true) return undefined;
+  const details = isRecord(message.details) ? message.details : undefined;
+  if (details?.op === 'view') return undefined;
+  return toPhases(details?.phases);
+}
+
+/** The chain of entry ids from the session's leaf back to the root. */
+function activeBranchIds(entries: TodoEntryLike[]): Set<string> {
+  const parentOf = new Map<string, string | null>();
+  for (const entry of entries) {
+    if (typeof entry.id !== 'string') continue;
+    parentOf.set(entry.id, typeof entry.parentId === 'string' ? entry.parentId : null);
+  }
+  const branch = new Set<string>();
+  // The leaf is the last entry in file order: omp appends as it advances, so
+  // the newest entry is where the conversation currently stands.
+  let cursor: string | null | undefined = undefined;
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const id = entries[i]?.id;
+    if (typeof id === 'string') {
+      cursor = id;
+      break;
+    }
+  }
+  while (typeof cursor === 'string' && !branch.has(cursor)) {
+    branch.add(cursor);
+    cursor = parentOf.get(cursor) ?? null;
+  }
+  return branch;
+}
+
+/**
+ * The deepest committed todo snapshot on the active branch, or null when this
+ * transcript holds none. The returned `sourceEntryId` is the entry a later
+ * snapshot has to beat — omp's own identity for the list.
+ */
+export function latestTodoSnapshot(entries: readonly unknown[]): TodoSnapshot | null {
+  const typed = entries as TodoEntryLike[];
+  const branch = activeBranchIds(typed);
+
+  for (let i = typed.length - 1; i >= 0; i--) {
+    const entry = typed[i];
+    const id = entry?.id;
+    // An entry with no id cannot be placed on the branch; a legacy file may
+    // still carry usable snapshots, so it is read but never claims identity.
+    if (typeof id === 'string' && !branch.has(id)) continue;
+    const phases = committedPhases(entry);
+    if (!phases) continue;
+    return {
+      phases,
+      sourceEntryId: typeof id === 'string' ? id : '',
+      source: entry.type === 'custom' ? 'custom' : 'toolResult',
+      ...(typeof entry.timestamp === 'string' ? { updatedAt: entry.timestamp } : {}),
+      ...readOp(entry),
+    };
+  }
+  return null;
+}
+
+/** Op + storage recorded on the snapshot entry, when it carries them. */
+function readOp(entry: TodoEntryLike): { op?: TodoOperation; storage?: 'session' | 'memory' } {
+  const details =
+    entry.type === 'message'
+      ? (isRecord(entry.message) ? (isRecord(entry.message.details) ? entry.message.details : undefined) : undefined)
+      : undefined;
+  if (!details) return {};
+  const op = typeof details.op === 'string' ? (details.op as TodoOperation) : undefined;
+  const storage = details.storage === 'session' || details.storage === 'memory' ? details.storage : undefined;
+  return { ...(op ? { op } : {}), ...(storage ? { storage } : {}) };
+}
+
+/** Counter roll-up over every task in a snapshot. */
+export function todoProgress(phases: readonly TodoPhase[]): TodoProgress {
+  const progress: TodoProgress = {
+    total: 0,
+    completed: 0,
+    closed: 0,
+    inProgress: 0,
+    pending: 0,
+    blocked: 0,
+    abandoned: 0,
+  };
+  for (const phase of phases) {
+    for (const task of phase.tasks) {
+      progress.total += 1;
+      switch (task.status) {
+        case 'completed':
+          progress.completed += 1;
+          progress.closed += 1;
+          break;
+        case 'abandoned':
+          progress.abandoned += 1;
+          progress.closed += 1;
+          break;
+        case 'in_progress':
+          progress.inProgress += 1;
+          break;
+        case 'blocked':
+          progress.blocked += 1;
+          break;
+        default:
+          progress.pending += 1;
+          break;
+      }
+    }
+  }
+  return progress;
+}
+
+/**
+ * The task the agent is on right now: an `in_progress` one if any, else the
+ * first `pending`. omp picks the same way for its own "next actionable" row.
+ */
+export function nextActionableTask(phases: readonly TodoPhase[]): TodoItem | undefined {
+  for (const phase of phases) {
+    for (const task of phase.tasks) {
+      if (task.status === 'in_progress') return task;
+    }
+  }
+  for (const phase of phases) {
+    for (const task of phase.tasks) {
+      if (task.status === 'pending') return task;
+    }
+  }
+  return undefined;
+}