jupyterlab-codex-sidebar 0.1.4 → 0.1.6

package/src/handlers/activitySummarizer.ts

@@ -0,0 +1,369 @@
+export type ActivityPhase = 'started' | 'completed' | '';
+export type ActivityCategory = 'reasoning' | 'command' | 'file' | 'tool' | 'event';
+
+export interface ActivitySummary {
+  activity: {
+    category: ActivityCategory;
+    phase: ActivityPhase;
+    title: string;
+    detail: string;
+    raw: string;
+  };
+  progress: string;
+  progressKind: '' | 'reasoning';
+}
+
+function truncateMiddle(value: string, max: number): string {
+  if (value.length <= max) {
+    return value;
+  }
+  const ellipsis = '...';
+  if (max <= ellipsis.length) {
+    return value.slice(0, max);
+  }
+  const head = Math.max(0, Math.floor((max - ellipsis.length) * 0.6));
+  const tail = Math.max(0, max - head - ellipsis.length);
+  return `${value.slice(0, head)}${ellipsis}${value.slice(value.length - tail)}`;
+}
+
+function safePreview(value: unknown, max = 220): string {
+  if (value == null) {
+    return '';
+  }
+  if (typeof value === 'string') {
+    return truncateMiddle(value, max);
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  try {
+    return truncateMiddle(JSON.stringify(value), max);
+  } catch {
+    return '';
+  }
+}
+
+function safeJsonPreview(value: any, maxChars = 6000): string {
+  try {
+    const text = JSON.stringify(value, null, 2);
+    if (text.length <= maxChars) {
+      return text;
+    }
+    return `${text.slice(0, Math.max(0, maxChars - 40))}\n... (truncated)`;
+  } catch {
+    return '';
+  }
+}
+
+function fileNameFromPath(path: string): string {
+  const raw = (path || '').trim();
+  if (!raw) {
+    return '';
+  }
+  const normalized = raw.replace(/\\/g, '/');
+  const parts = normalized.split('/').filter(Boolean);
+  return parts[parts.length - 1] || normalized;
+}
+
+function extractFileChangePaths(item: any): string[] {
+  if (!item || typeof item !== 'object') {
+    return [];
+  }
+
+  const seen = new Set<string>();
+  const paths: string[] = [];
+  const push = (value: unknown): void => {
+    if (typeof value !== 'string') {
+      return;
+    }
+    const path = value.trim();
+    if (!path || seen.has(path)) {
+      return;
+    }
+    seen.add(path);
+    paths.push(path);
+  };
+
+  const directKeys = [
+    'path',
+    'filename',
+    'filePath',
+    'file_path',
+    'targetPath',
+    'target_path',
+    'newPath',
+    'new_path',
+    'oldPath',
+    'old_path',
+    'sourcePath',
+    'source_path',
+    'destinationPath',
+    'destination_path'
+  ];
+  for (const key of directKeys) {
+    push(item[key]);
+  }
+
+  const nestedObjectKeys = ['file', 'target', 'source', 'destination'];
+  for (const key of nestedObjectKeys) {
+    const nested = item[key];
+    if (!nested || typeof nested !== 'object') {
+      continue;
+    }
+    push((nested as any).path);
+    push((nested as any).filename);
+    push((nested as any).filePath);
+    push((nested as any).file_path);
+  }
+
+  const listKeys = ['paths', 'files', 'changes', 'edits'];
+  for (const key of listKeys) {
+    const list = item[key];
+    if (!Array.isArray(list)) {
+      continue;
+    }
+    for (const entry of list) {
+      if (typeof entry === 'string') {
+        push(entry);
+        continue;
+      }
+      if (!entry || typeof entry !== 'object') {
+        continue;
+      }
+      push((entry as any).path);
+      push((entry as any).filename);
+      push((entry as any).filePath);
+      push((entry as any).file_path);
+      push((entry as any).targetPath);
+      push((entry as any).target_path);
+      push((entry as any).newPath);
+      push((entry as any).new_path);
+      push((entry as any).oldPath);
+      push((entry as any).old_path);
+    }
+  }
+
+  // Fallback: recursively scan nested objects for path-like keys.
+  if (paths.length === 0) {
+    const queue: unknown[] = [item];
+    let visited = 0;
+    while (queue.length > 0 && visited < 300) {
+      const current = queue.shift();
+      visited += 1;
+      if (!current || typeof current !== 'object') {
+        continue;
+      }
+      if (Array.isArray(current)) {
+        for (const value of current) {
+          queue.push(value);
+        }
+        continue;
+      }
+
+      for (const [rawKey, value] of Object.entries(current as Record<string, unknown>)) {
+        const key = rawKey.trim().toLowerCase();
+        if (
+          typeof value === 'string' &&
+          (key === 'filename' ||
+            key.endsWith('path') ||
+            key.endsWith('_path') ||
+            key.endsWith('filepath') ||
+            key.endsWith('file_path'))
+        ) {
+          push(value);
+        }
+        if (value && typeof value === 'object') {
+          queue.push(value);
+        }
+      }
+    }
+  }
+
+  return paths;
+}
+
+function humanizeToken(value: string): string {
+  const input = (value || '').trim();
+  if (!input) {
+    return '';
+  }
+  return input
+    .split(/[_-]+/)
+    .filter(Boolean)
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+export function summarizeCodexEvent(payload: any): ActivitySummary {
+  if (!payload || typeof payload !== 'object') {
+    return {
+      progress: 'Event',
+      progressKind: '',
+      activity: { category: 'event', phase: '', title: 'Event', detail: '', raw: safeJsonPreview(payload) }
+    };
+  }
+
+  const type =
+    (typeof payload.type === 'string' && payload.type) ||
+    (typeof payload.event === 'string' && payload.event) ||
+    'event';
+  const raw = safeJsonPreview(payload);
+
+  // Common Codex CLI shape: { type: "item.completed|item.started", item: { type: "...", ... } }
+  if (
+    (type === 'item.completed' || type === 'item.started') &&
+    payload.item &&
+    typeof payload.item === 'object'
+  ) {
+    const item: any = payload.item;
+    const itemType = typeof item.type === 'string' ? item.type : '';
+    const toolName =
+      (typeof item.tool_name === 'string' && item.tool_name) ||
+      (typeof item.tool === 'string' && item.tool) ||
+      (typeof item.name === 'string' && item.name) ||
+      '';
+    const path = (typeof item.path === 'string' && item.path) || (typeof item.filename === 'string' && item.filename) || '';
+    const phase: ActivityPhase = type === 'item.started' ? 'started' : type === 'item.completed' ? 'completed' : '';
+
+    let category: ActivityCategory = 'event';
+    let progressKind: '' | 'reasoning' = '';
+
+    if (itemType === 'reasoning') {
+      category = 'reasoning';
+      progressKind = 'reasoning';
+    } else if (itemType === 'command_execution') {
+      category = 'command';
+    } else if (itemType === 'file_change') {
+      category = 'file';
+    } else if (toolName) {
+      category = 'tool';
+    }
+
+    let title = '';
+    let detail = '';
+
+    if (itemType === 'command_execution') {
+      const commandField =
+        item.command ?? item.cmd ?? item.shell_command ?? item.argv ?? item.args ?? item.commandLine ?? item.command_line;
+      let commandHint = '';
+      if (typeof commandField === 'string') {
+        commandHint = commandField;
+      } else if (
+        Array.isArray(commandField) &&
+        commandField.length > 0 &&
+        commandField.every((token: any) => typeof token === 'string')
+      ) {
+        commandHint = commandField.join(' ');
+      } else {
+        commandHint = safePreview(commandField);
+      }
+      const exitCode = typeof item.exit_code === 'number' ? item.exit_code : typeof item.exitCode === 'number' ? item.exitCode : null;
+      title = phase === 'started' ? 'Running command' : phase === 'completed' ? 'Command finished' : 'Command';
+      detail = commandHint || '';
+      if (exitCode != null) {
+        detail = detail ? `${detail}\n(exit ${exitCode})` : `(exit ${exitCode})`;
+      }
+    } else if (itemType === 'file_change') {
+      const filePaths = extractFileChangePaths(item);
+      const primaryPath = filePaths[0] || path || '';
+      const fileName = fileNameFromPath(primaryPath);
+      const baseTitle = phase === 'started' ? 'Update file' : phase === 'completed' ? 'File updated' : 'File change';
+      title = fileName ? `${baseTitle}: ${fileName}` : baseTitle;
+      detail = filePaths.length > 0 ? filePaths.join('\n') : path || '';
+    } else if (itemType === 'reasoning') {
+      title = phase === 'started' ? 'Reasoning' : phase === 'completed' ? 'Reasoning step' : 'Reasoning';
+      detail = toolName ? `(${toolName})` : '';
+    } else {
+      const base = humanizeToken(itemType) || humanizeToken(type) || 'Event';
+      title = phase === 'started' ? `${base} started` : phase === 'completed' ? `${base} completed` : base;
+      const detailParts: string[] = [];
+      if (toolName) {
+        detailParts.push(`tool: ${toolName}`);
+      }
+      if (path) {
+        detailParts.push(`path: ${path}`);
+      }
+      detail = detailParts.join('\n');
+    }
+
+    if (!title) {
+      title = humanizeToken(itemType) || 'Event';
+    }
+    detail = truncateMiddle(detail, 1400);
+
+    const progressParts: string[] = [];
+    if (title) {
+      progressParts.push(title);
+    }
+    if (detail) {
+      const oneLine = detail.replace(/\s+/g, ' ').trim();
+      progressParts.push(truncateMiddle(oneLine, 200));
+    }
+    const progress = progressParts.join(': ') || humanizeToken(type) || 'Event';
+
+    return {
+      progress,
+      progressKind,
+      activity: {
+        category,
+        phase,
+        title,
+        detail,
+        raw
+      }
+    };
+  }
+
+  const label =
+    (typeof payload.name === 'string' && payload.name) ||
+    (typeof payload.label === 'string' && payload.label) ||
+    (typeof payload.tool_name === 'string' && payload.tool_name) ||
+    (typeof payload.tool === 'string' && payload.tool) ||
+    '';
+  if (label && label !== type) {
+    const progress = `${humanizeToken(type) || type}: ${truncateMiddle(label, 120)}`;
+    return {
+      progress,
+      progressKind: '',
+      activity: { category: 'event', phase: '', title: humanizeToken(type) || type, detail: label, raw }
+    };
+  }
+
+  const commandHint = safePreview(payload.command);
+  if (commandHint) {
+    const progress = `${humanizeToken(type) || type}: ${commandHint}`;
+    return {
+      progress,
+      progressKind: '',
+      activity: { category: 'event', phase: '', title: humanizeToken(type) || type, detail: commandHint, raw }
+    };
+  }
+
+  const pathHint = safePreview(payload.path);
+  if (pathHint) {
+    const progress = `${humanizeToken(type) || type}: ${pathHint}`;
+    return {
+      progress,
+      progressKind: '',
+      activity: { category: 'event', phase: '', title: humanizeToken(type) || type, detail: pathHint, raw }
+    };
+  }
+
+  return {
+    progress: humanizeToken(type) || type,
+    progressKind: '',
+    activity: { category: 'event', phase: '', title: humanizeToken(type) || type, detail: '', raw }
+  };
+}
+
+export function isNoiseCodexEvent(payload: any): boolean {
+  if (!payload || typeof payload !== 'object') {
+    return false;
+  }
+  const type =
+    (typeof payload.type === 'string' && payload.type) ||
+    (typeof payload.event === 'string' && payload.event) ||
+    '';
+  // These are useful for debugging but not meaningful for end users.
+  return type === 'thread.started' || type === 'turn.started' || type === 'turn.completed';
+}

package/src/handlers/codexMessageTypes.ts

@@ -0,0 +1,34 @@
+export type TextRole = 'user' | 'assistant' | 'system';
+
+export interface HistoryEntry {
+  role: TextRole;
+  content: string;
+  selectionPreview?: {
+    locationLabel: string;
+    previewText: string;
+  };
+  cellOutputPreview?: {
+    locationLabel: string;
+    previewText: string;
+  };
+}
+
+export interface RateLimitWindowSnapshot {
+  usedPercent: number | null;
+  windowMinutes: number | null;
+  resetsAt: number | null;
+}
+
+export interface ContextWindowSnapshot {
+  windowTokens: number | null;
+  usedTokens: number | null;
+  leftTokens: number | null;
+  usedPercent: number | null;
+}
+
+export interface CodexRateLimitsSnapshot {
+  updatedAt: string | null;
+  primary: RateLimitWindowSnapshot | null;
+  secondary: RateLimitWindowSnapshot | null;
+  contextWindow: ContextWindowSnapshot | null;
+}

package/src/handlers/codexMessageUtils.ts

@@ -0,0 +1,217 @@
+import type {
+  CodexRateLimitsSnapshot,
+  ContextWindowSnapshot,
+  HistoryEntry,
+  RateLimitWindowSnapshot,
+  TextRole
+} from './codexMessageTypes';
+
+export type { HistoryEntry, TextRole };
+
+export type ProgressKind = '' | 'reasoning';
+export type ActivityPhase = 'started' | 'completed' | '';
+export type ActivityCategory = 'reasoning' | 'command' | 'file' | 'tool' | 'event';
+
+export interface SelectionPreview {
+  locationLabel: string;
+  previewText: string;
+}
+
+export interface MessageContextPreview {
+  selectionPreview?: SelectionPreview;
+  cellOutputPreview?: SelectionPreview;
+}
+
+export interface ActivityItem {
+  category: ActivityCategory;
+  phase: ActivityPhase;
+  title: string;
+  detail: string;
+  raw: string;
+}
+
+export interface ActivitySummary {
+  activity: Omit<ActivityItem, 'id' | 'ts'>;
+  progress: string;
+  progressKind: ProgressKind;
+}
+
+export interface SessionPreviewSplit {
+  selectionPreview?: unknown;
+  cellOutputPreview?: unknown;
+}
+
+export function truncateEnd(text: string, max: number): string {
+  if (text.length <= max) {
+    return text;
+  }
+  if (max <= 3) {
+    return text.slice(0, max);
+  }
+  return `${text.slice(0, max - 3)}...`;
+}
+
+export function coerceSelectionPreview(
+  value: unknown,
+  options: {
+    maxChars?: number;
+    normalize?: (value: string) => string;
+  } = {}
+): SelectionPreview | undefined {
+  if (!value || typeof value !== 'object') {
+    return undefined;
+  }
+  const raw = value as Record<string, unknown>;
+  const locationLabel = typeof raw.locationLabel === 'string' ? raw.locationLabel.trim() : '';
+  const normalizer = options.normalize ?? ((text: string) => text.trim());
+  const maxChars = options.maxChars ?? 500;
+  const previewText =
+    typeof raw.previewText === 'string' ? truncateEnd(normalizer(raw.previewText), maxChars) : '';
+  if (!locationLabel || !previewText) {
+    return undefined;
+  }
+  return { locationLabel, previewText };
+}
+
+export function coerceMessageContextPreview(
+  value: unknown,
+  options: {
+    maxChars?: number;
+    normalize?: (value: string) => string;
+  } = {}
+): MessageContextPreview | undefined {
+  if (!value || typeof value !== 'object') {
+    return undefined;
+  }
+  const raw = value as Record<string, unknown>;
+  const selectionPreview = coerceSelectionPreview(raw.selectionPreview, options);
+  const cellOutputPreview = coerceSelectionPreview(raw.cellOutputPreview, options);
+  if (selectionPreview || cellOutputPreview) {
+    return {
+      ...(selectionPreview ? { selectionPreview } : {}),
+      ...(cellOutputPreview ? { cellOutputPreview } : {})
+    };
+  }
+
+  // Legacy format: a single preview object was stored directly as selection preview.
+  const legacySelectionPreview = coerceSelectionPreview(raw, options);
+  if (legacySelectionPreview) {
+    return { selectionPreview: legacySelectionPreview };
+  }
+  return undefined;
+}
+
+export function coerceSessionHistory(
+  raw: unknown,
+  options: {
+    maxChars?: number;
+    normalize?: (value: string) => string;
+  } = {}
+): HistoryEntry[] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  const result: HistoryEntry[] = [];
+  for (const item of raw) {
+    if (!item || typeof item !== 'object') {
+      continue;
+    }
+    const role = (item as any).role;
+    const content = (item as any).content;
+    if ((role !== 'user' && role !== 'assistant' && role !== 'system') || typeof content !== 'string') {
+      continue;
+    }
+    const selectionPreview = coerceSelectionPreview((item as any).selectionPreview, options);
+    const cellOutputPreview = coerceSelectionPreview((item as any).cellOutputPreview, options);
+    result.push({
+      role,
+      content,
+      selectionPreview,
+      cellOutputPreview
+    });
+  }
+  return result;
+}
+
+function coerceFiniteNumber(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      return null;
+    }
+    const parsed = Number(trimmed);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+export function coerceRateLimitWindow(raw: unknown): RateLimitWindowSnapshot | null {
+  if (!raw || typeof raw !== 'object') {
+    return null;
+  }
+  const record = raw as Record<string, unknown>;
+  const usedPercent = coerceFiniteNumber(record.usedPercent);
+  const windowMinutesValue = coerceFiniteNumber(record.windowMinutes);
+  const resetsAtValue = coerceFiniteNumber(record.resetsAt);
+  const windowMinutes = windowMinutesValue === null ? null : Math.round(windowMinutesValue);
+  const resetsAt = resetsAtValue === null ? null : Math.round(resetsAtValue);
+  return { usedPercent, windowMinutes, resetsAt };
+}
+
+export function coerceContextWindowSnapshot(raw: unknown): ContextWindowSnapshot | null {
+  if (!raw || typeof raw !== 'object') {
+    return null;
+  }
+  const record = raw as Record<string, unknown>;
+  const windowTokensValue = coerceFiniteNumber(record.windowTokens);
+  const usedTokensValue = coerceFiniteNumber(record.usedTokens);
+  const leftTokensValue = coerceFiniteNumber(record.leftTokens);
+  const usedPercent = coerceFiniteNumber(record.usedPercent);
+  const windowTokens = windowTokensValue === null ? null : Math.round(windowTokensValue);
+  const usedTokens = usedTokensValue === null ? null : Math.round(usedTokensValue);
+  const leftTokens = leftTokensValue === null ? null : Math.round(leftTokensValue);
+  if (windowTokens == null && usedTokens == null && leftTokens == null && usedPercent == null) {
+    return null;
+  }
+  return { windowTokens, usedTokens, leftTokens, usedPercent };
+}
+
+export function coerceRateLimitsSnapshot(raw: unknown): CodexRateLimitsSnapshot | null {
+  if (!raw || typeof raw !== 'object') {
+    return null;
+  }
+  const rawRecord = raw as Record<string, unknown>;
+  const updatedAt = typeof rawRecord.updatedAt === 'string' && rawRecord.updatedAt.trim() ? rawRecord.updatedAt : null;
+  return {
+    updatedAt,
+    primary: coerceRateLimitWindow(rawRecord.primary),
+    secondary: coerceRateLimitWindow(rawRecord.secondary),
+    contextWindow: coerceContextWindowSnapshot(rawRecord.contextWindow)
+  };
+}
+
+export function splitStoredMessagePreview(value: unknown): SessionPreviewSplit {
+  if (!value || typeof value !== 'object') {
+    return {};
+  }
+
+  const raw = value as Record<string, unknown>;
+  const hasNestedPreview =
+    Object.prototype.hasOwnProperty.call(raw, 'selectionPreview') ||
+    Object.prototype.hasOwnProperty.call(raw, 'cellOutputPreview');
+  if (hasNestedPreview) {
+    return {
+      selectionPreview: raw.selectionPreview,
+      cellOutputPreview: raw.cellOutputPreview
+    };
+  }
+
+  // Legacy format: a single preview object was stored directly as selectionPreview.
+  if (Object.prototype.hasOwnProperty.call(raw, 'locationLabel') && Object.prototype.hasOwnProperty.call(raw, 'previewText')) {
+    return { selectionPreview: raw };
+  }
+  return {};
+}