@rmrdeveloper/sideroom-pi 5.0.1 → 7.0.0

package/extensions/modified-files/index.ts

@@ -0,0 +1,45 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from '@earendil-works/pi-coding-agent';
+import { TODO_WIDGET_REFRESH_EVENT } from '../todo/session.ts';
+import {
+  commitModifiedFiles,
+  createModifiedFilesStore,
+  refreshModifiedFiles,
+  registerModifiedFilesEvents,
+} from './session.ts';
+import { createModifiedFilesOverlayController } from './ui.ts';
+
+const SHORTCUT = 'f8';
+
+// Pi loads extensions/*/index.ts through export default.
+export default function registerModifiedFiles(pi: ExtensionAPI): void {
+  const store = createModifiedFilesStore();
+  const overlay = createModifiedFilesOverlayController(
+    () => store.files,
+    (ctx) => commitModifiedFiles(store, pi, ctx, []),
+  );
+
+  registerModifiedFilesEvents(pi, store);
+  pi.events.on(TODO_WIDGET_REFRESH_EVENT, (value) => {
+    if (isWidgetContext(value)) {
+      refreshModifiedFiles(store, value);
+    }
+  });
+  pi.registerShortcut(SHORTCUT, {
+    description: 'Toggle edited files',
+    handler: (ctx) => overlay.toggle(ctx),
+  });
+}
+
+function isWidgetContext(
+  value: unknown,
+): value is Pick<ExtensionContext, 'ui' | 'cwd'> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'ui' in value &&
+    'cwd' in value
+  );
+}

package/extensions/modified-files/model.ts

@@ -0,0 +1,74 @@
+import { relative, resolve } from 'node:path';
+
+export const MAX_TRACKED_FILES = 100;
+export const MODIFIED_FILES_SNAPSHOT_TYPE = 'sideroom-modified-files';
+export const MODIFIED_FILES_WIDGET_KEY = 'sideroom-modified-files';
+
+export const FILE_TOOL_NAME = {
+  edit: 'edit',
+  write: 'write',
+} as const;
+
+export type FileToolName = (typeof FILE_TOOL_NAME)[keyof typeof FILE_TOOL_NAME];
+
+export interface ModifiedFile {
+  readonly path: string;
+  readonly toolName: FileToolName;
+}
+
+export function recordModifiedFile(
+  files: readonly ModifiedFile[],
+  path: string,
+  toolName: FileToolName,
+): readonly ModifiedFile[] {
+  return [
+    { path, toolName },
+    ...files.filter((file) => file.path !== path),
+  ].slice(0, MAX_TRACKED_FILES);
+}
+
+export function resolveModifiedPath(
+  cwd: string,
+  path: string,
+): string | undefined {
+  const normalized = path.trim().replace(/^@/, '');
+  if (normalized.length === 0) {
+    return undefined;
+  }
+  return resolve(cwd, normalized);
+}
+
+export function displayModifiedPath(cwd: string, path: string): string {
+  const displayPath = relative(cwd, path);
+  if (displayPath === '' || displayPath.startsWith('..')) {
+    return `external: ${path}`;
+  }
+  return displayPath;
+}
+
+export function readModifiedFilesSnapshot(
+  value: unknown,
+): readonly ModifiedFile[] | undefined {
+  if (!isRecord(value) || !Array.isArray(value.files)) {
+    return undefined;
+  }
+
+  const files: ModifiedFile[] = [];
+  for (const file of value.files) {
+    if (!isRecord(file) || typeof file.path !== 'string') {
+      return undefined;
+    }
+    if (
+      file.toolName !== FILE_TOOL_NAME.edit &&
+      file.toolName !== FILE_TOOL_NAME.write
+    ) {
+      return undefined;
+    }
+    files.push({ path: file.path, toolName: file.toolName });
+  }
+  return files;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/extensions/modified-files/session.ts

@@ -0,0 +1,200 @@
+import { resolve } from 'node:path';
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from '@earendil-works/pi-coding-agent';
+import {
+  isEditToolResult,
+  isWriteToolResult,
+} from '@earendil-works/pi-coding-agent';
+import {
+  type FileToolName,
+  MODIFIED_FILES_SNAPSHOT_TYPE,
+  MODIFIED_FILES_WIDGET_KEY,
+  type ModifiedFile,
+  readModifiedFilesSnapshot,
+  recordModifiedFile,
+  resolveModifiedPath,
+} from './model.ts';
+import { renderModifiedFilesWidget } from './ui.ts';
+
+export interface ModifiedFilesStore {
+  files: readonly ModifiedFile[];
+}
+
+type SessionBranch = ReturnType<
+  ExtensionContext['sessionManager']['getBranch']
+>;
+
+export function createModifiedFilesStore(
+  files: readonly ModifiedFile[] = [],
+): ModifiedFilesStore {
+  return { files };
+}
+
+export function reconstructModifiedFiles(
+  branch: SessionBranch,
+): readonly ModifiedFile[] {
+  for (let index = branch.length - 1; index >= 0; index -= 1) {
+    const entry = branch[index];
+    if (
+      entry?.type !== 'custom' ||
+      entry.customType !== MODIFIED_FILES_SNAPSHOT_TYPE
+    ) {
+      continue;
+    }
+    const files = readModifiedFilesSnapshot(entry.data);
+    if (files !== undefined) {
+      return files;
+    }
+  }
+  return reconstructFromToolResults(branch);
+}
+
+export function restoreModifiedFiles(
+  store: ModifiedFilesStore,
+  ctx: Pick<ExtensionContext, 'sessionManager' | 'cwd'>,
+): void {
+  store.files = reconstructModifiedFiles(ctx.sessionManager.getBranch()).map(
+    (file) => ({
+      ...file,
+      path: resolve(ctx.cwd, file.path),
+    }),
+  );
+}
+
+export function refreshModifiedFiles(
+  store: ModifiedFilesStore,
+  ctx: Pick<ExtensionContext, 'ui' | 'cwd'>,
+): void {
+  if (store.files.length === 0) {
+    ctx.ui.setWidget(MODIFIED_FILES_WIDGET_KEY, undefined);
+    return;
+  }
+  ctx.ui.setWidget(MODIFIED_FILES_WIDGET_KEY, (_tui, theme) => {
+    const lines = renderModifiedFilesWidget(store.files, ctx.cwd, theme);
+    return {
+      render: () => lines ?? [],
+      invalidate() {},
+    };
+  });
+}
+
+export function restoreAndRefreshModifiedFiles(
+  store: ModifiedFilesStore,
+  ctx: Pick<ExtensionContext, 'sessionManager' | 'ui' | 'cwd'>,
+): void {
+  restoreModifiedFiles(store, ctx);
+  refreshModifiedFiles(store, ctx);
+}
+
+export function commitModifiedFiles(
+  store: ModifiedFilesStore,
+  pi: Pick<ExtensionAPI, 'appendEntry'>,
+  ctx: Pick<ExtensionContext, 'ui' | 'cwd'>,
+  files: readonly ModifiedFile[],
+): void {
+  store.files = files;
+  pi.appendEntry(MODIFIED_FILES_SNAPSHOT_TYPE, { files });
+  refreshModifiedFiles(store, ctx);
+}
+
+export function registerModifiedFilesEvents(
+  pi: ExtensionAPI,
+  store: ModifiedFilesStore,
+): void {
+  pi.on('session_start', (_event, ctx) =>
+    restoreAndRefreshModifiedFiles(store, ctx),
+  );
+  pi.on('session_tree', (_event, ctx) =>
+    restoreAndRefreshModifiedFiles(store, ctx),
+  );
+  pi.on('session_compact', (_event, ctx) =>
+    restoreAndRefreshModifiedFiles(store, ctx),
+  );
+  pi.on('tool_result', (event, ctx) => {
+    if (
+      event.isError ||
+      (!isEditToolResult(event) && !isWriteToolResult(event))
+    ) {
+      return;
+    }
+    const path = readToolPath(event.input);
+    if (path === undefined) {
+      return;
+    }
+    const resolvedPath = resolveModifiedPath(ctx.cwd, path);
+    if (resolvedPath === undefined) {
+      return;
+    }
+    const files = recordModifiedFile(store.files, resolvedPath, event.toolName);
+    commitModifiedFiles(store, pi, ctx, files);
+  });
+}
+
+function reconstructFromToolResults(
+  branch: SessionBranch,
+): readonly ModifiedFile[] {
+  const calls = collectFileToolCalls(branch);
+  let files: readonly ModifiedFile[] = [];
+
+  for (const entry of branch) {
+    const file = fileFromToolResult(entry, calls);
+    if (file !== undefined) {
+      files = recordModifiedFile(files, file.path, file.toolName);
+    }
+  }
+  return files;
+}
+
+function collectFileToolCalls(
+  branch: SessionBranch,
+): Map<string, ModifiedFile> {
+  const calls = new Map<string, ModifiedFile>();
+  for (const entry of branch) {
+    if (entry?.type !== 'message' || entry.message.role !== 'assistant') {
+      continue;
+    }
+    for (const content of entry.message.content) {
+      if (content.type !== 'toolCall') {
+        continue;
+      }
+      const toolName = fileToolName(content.name);
+      const path = readToolPath(content.arguments);
+      if (toolName !== undefined && path !== undefined) {
+        calls.set(content.id, { path, toolName });
+      }
+    }
+  }
+  return calls;
+}
+
+function fileFromToolResult(
+  entry: SessionBranch[number] | undefined,
+  calls: ReadonlyMap<string, ModifiedFile>,
+): ModifiedFile | undefined {
+  if (entry?.type !== 'message' || entry.message.role !== 'toolResult') {
+    return undefined;
+  }
+  const message = entry.message;
+  if (message.isError) {
+    return undefined;
+  }
+  const toolName = fileToolName(message.toolName);
+  const call = calls.get(message.toolCallId);
+  if (toolName === undefined || call?.toolName !== toolName) {
+    return undefined;
+  }
+  return call;
+}
+
+function fileToolName(value: string): FileToolName | undefined {
+  if (value === 'edit' || value === 'write') {
+    return value;
+  }
+  return undefined;
+}
+
+function readToolPath(input: Record<string, unknown>): string | undefined {
+  return typeof input.path === 'string' ? input.path : undefined;
+}

package/extensions/modified-files/ui.ts

@@ -0,0 +1,207 @@
+import { pathToFileURL } from 'node:url';
+import type { ExtensionContext, Theme } from '@earendil-works/pi-coding-agent';
+import {
+  type Component,
+  Key,
+  matchesKey,
+  type TUI,
+  truncateToWidth,
+} from '@earendil-works/pi-tui';
+import { displayModifiedPath, type ModifiedFile } from './model.ts';
+
+const COMPACT_FILE_LIMIT = 5;
+const EXTENDED_FILE_LIMIT = 12;
+
+export function renderModifiedFilesWidget(
+  files: readonly ModifiedFile[],
+  cwd: string,
+  theme: Theme,
+): string[] | undefined {
+  if (files.length === 0) {
+    return undefined;
+  }
+
+  const visibleFiles = files.slice(0, COMPACT_FILE_LIMIT);
+  const lines = [
+    '',
+    theme.fg(
+      'dim',
+      `── Edited files this session (${String(files.length)}) ──`,
+    ),
+    ...visibleFiles.map((file) => renderFileLine(file, cwd, theme)),
+  ];
+  lines.push(theme.fg('dim', 'F8: view all'));
+  return lines;
+}
+
+export interface ModifiedFilesOverlayController {
+  toggle(ctx: ExtensionContext): void;
+}
+
+export function createModifiedFilesOverlayController(
+  files: () => readonly ModifiedFile[],
+  clearFiles: (ctx: ExtensionContext) => void,
+): ModifiedFilesOverlayController {
+  let close: (() => void) | undefined;
+  let opening = false;
+
+  return {
+    toggle(ctx) {
+      if (close !== undefined) {
+        close();
+        return;
+      }
+      if (opening || ctx.mode !== 'tui') {
+        return;
+      }
+
+      opening = true;
+      void ctx.ui
+        .custom<void>(
+          (tui, theme, _keybindings, done) => {
+            close = done;
+            return new ModifiedFilesOverlay(
+              tui,
+              files,
+              ctx.cwd,
+              theme,
+              done,
+              () => clearFiles(ctx),
+            );
+          },
+          {
+            overlay: true,
+            overlayOptions: {
+              anchor: 'center',
+              width: '70%',
+              minWidth: 40,
+              maxHeight: '80%',
+              visible: (terminalWidth) => terminalWidth >= 60,
+            },
+          },
+        )
+        .finally(() => {
+          close = undefined;
+          opening = false;
+        });
+    },
+  };
+}
+
+export class ModifiedFilesOverlay implements Component {
+  private offset = 0;
+  private readonly tui: TUI;
+  private readonly files: () => readonly ModifiedFile[];
+  private readonly cwd: string;
+  private readonly theme: Theme;
+  private readonly close: () => void;
+  private readonly clear: () => void;
+
+  constructor(
+    tui: TUI,
+    files: () => readonly ModifiedFile[],
+    cwd: string,
+    theme: Theme,
+    close: () => void,
+    clear: () => void,
+  ) {
+    this.tui = tui;
+    this.files = files;
+    this.cwd = cwd;
+    this.theme = theme;
+    this.close = close;
+    this.clear = clear;
+  }
+
+  handleInput(data: string): void {
+    const maxOffset = Math.max(0, this.files().length - EXTENDED_FILE_LIMIT);
+    if (matchesKey(data, Key.escape) || matchesKey(data, Key.f8)) {
+      this.close();
+      return;
+    }
+    if (matchesKey(data, 'r')) {
+      this.clear();
+      this.close();
+      return;
+    }
+    if (matchesKey(data, Key.up)) {
+      this.offset = Math.max(0, this.offset - 1);
+      this.tui.requestRender();
+      return;
+    }
+    if (matchesKey(data, Key.down)) {
+      this.offset = Math.min(maxOffset, this.offset + 1);
+      this.tui.requestRender();
+      return;
+    }
+    if (matchesKey(data, Key.pageUp)) {
+      this.offset = Math.max(0, this.offset - EXTENDED_FILE_LIMIT);
+      this.tui.requestRender();
+      return;
+    }
+    if (matchesKey(data, Key.pageDown)) {
+      this.offset = Math.min(maxOffset, this.offset + EXTENDED_FILE_LIMIT);
+      this.tui.requestRender();
+    }
+  }
+
+  render(width: number): string[] {
+    const innerWidth = Math.max(1, width - 2);
+    const files = this.files();
+    const visibleFiles = files.slice(
+      this.offset,
+      this.offset + EXTENDED_FILE_LIMIT,
+    );
+    const border = (text: string) => this.theme.fg('border', text);
+    const line = (text: string) => truncateToWidth(text, innerWidth, '…', true);
+    const title = line(
+      ` Edited files during this session (${String(files.length)}) `,
+    );
+    const lines = [
+      border(`╭${'─'.repeat(innerWidth)}╮`),
+      `${border('│')}${line(this.theme.fg('accent', this.theme.bold(title)))}${border('│')}`,
+      `${border('├')}${border('─'.repeat(innerWidth))}${border('┤')}`,
+    ];
+
+    for (const file of visibleFiles) {
+      lines.push(
+        `${border('│')}${line(renderFileLine(file, this.cwd, this.theme))}${border('│')}`,
+      );
+    }
+    if (visibleFiles.length === 0) {
+      lines.push(
+        `${border('│')}${line(this.theme.fg('muted', ' No files edited yet.'))}${border('│')}`,
+      );
+    }
+
+    const scrollHint = files.length > EXTENDED_FILE_LIMIT ? ' ↑↓ scroll ·' : '';
+    lines.push(`${border('├')}${border('─'.repeat(innerWidth))}${border('┤')}`);
+    lines.push(
+      `${border('│')}${line(this.theme.fg('dim', `${scrollHint} R clear · F8 or Esc close`))}${border('│')}`,
+    );
+    lines.push(border(`╰${'─'.repeat(innerWidth)}╯`));
+    return lines;
+  }
+
+  invalidate(): void {}
+}
+
+function renderFileLine(file: ModifiedFile, cwd: string, theme: Theme): string {
+  const operation = file.toolName === 'write' ? 'write' : 'edit';
+  const path = displayModifiedPath(cwd, file.path);
+  return ` ${theme.fg('muted', `${operation} `)}${fileHyperlink(file.path, path)}`;
+}
+
+function fileHyperlink(path: string, label: string): string {
+  const target = pathToFileURL(path).href;
+  return `\u001B]8;;${target}\u0007${safeLabel(label)}\u001B]8;;\u0007`;
+}
+
+function safeLabel(value: string): string {
+  return [...value]
+    .map((character) => {
+      const codePoint = character.codePointAt(0) ?? 0;
+      return codePoint < 32 || codePoint === 127 ? '?' : character;
+    })
+    .join('');
+}

package/extensions/todo/execute.ts

@@ -0,0 +1,69 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import {
+  applyTodoParams,
+  parseTodoParams,
+  TODO_ACTION,
+  type TodoAction,
+  type TodoItem,
+  type TodoParams,
+  UI_UNAVAILABLE,
+} from './model.ts';
+
+export interface TodoToolDetails {
+  readonly action?: TodoAction;
+  readonly items: readonly TodoItem[];
+  readonly error?: string;
+}
+
+export interface TodoToolResult {
+  readonly content: [{ readonly type: 'text'; readonly text: string }];
+  readonly details: TodoToolDetails;
+}
+
+export function executeTodo(
+  params: TodoParams,
+  ctx: Pick<ExtensionContext, 'mode'>,
+  currentItems: readonly TodoItem[],
+): TodoToolResult {
+  const parsed = parseTodoParams(params);
+  if (!parsed.ok) {
+    return errorResult(parsed.message, currentItems);
+  }
+  if (parsed.params.action === TODO_ACTION.propose && ctx.mode !== 'tui') {
+    return errorResult(UI_UNAVAILABLE, currentItems, parsed.params.action);
+  }
+
+  const applied = applyTodoParams(currentItems, parsed.params);
+  if (!applied.ok) {
+    return errorResult(applied.message, currentItems, parsed.params.action);
+  }
+
+  const itemCount = applied.items.length;
+  return {
+    content: [
+      { type: 'text', text: successMessage(parsed.params.action, itemCount) },
+    ],
+    details: { action: parsed.params.action, items: applied.items },
+  };
+}
+
+function successMessage(action: TodoAction, itemCount: number): string {
+  if (action === TODO_ACTION.propose) {
+    if (itemCount === 0) {
+      return 'Board cleared';
+    }
+    return `Board proposed with ${String(itemCount)} item${itemCount === 1 ? '' : 's'}`;
+  }
+  return `Board updated (${String(itemCount)} item${itemCount === 1 ? '' : 's'})`;
+}
+
+function errorResult(
+  error: string,
+  items: readonly TodoItem[],
+  action?: TodoToolDetails['action'],
+): TodoToolResult {
+  return {
+    content: [{ type: 'text', text: error }],
+    details: { action, items, error },
+  };
+}

package/extensions/todo/guards.ts

@@ -0,0 +1,107 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from '@earendil-works/pi-coding-agent';
+import {
+  shouldNudgePropose,
+  shouldWatchdogUpdate,
+  TOOL_NAME,
+} from './model.ts';
+import type { TodoStore } from './session.ts';
+
+const NUDGE_TYPE = 'sideroom-todo-nudge';
+const WATCHDOG_TYPE = 'sideroom-todo-watchdog';
+const MUTATING_TOOL_NAMES = new Set(['write', 'edit', 'bash']);
+
+interface TodoRunState {
+  proposeNudgedThisRun: boolean;
+  updateWatchdogThisTurn: boolean;
+  turnMutated: boolean;
+  turnCalledTodo: boolean;
+  steerFromUs: boolean;
+}
+
+export function registerGuardEvents(
+  pi: ExtensionAPI,
+  store: TodoStore,
+  restore: (ctx: ExtensionContext) => void,
+): void {
+  const runState = createTodoRunState();
+
+  pi.on('input', (event) => {
+    if (event.source === 'interactive' || event.source === 'rpc') {
+      runState.proposeNudgedThisRun = false;
+      runState.steerFromUs = false;
+    }
+  });
+
+  pi.on('turn_start', () => resetTurnState(runState));
+
+  pi.on('tool_execution_start', (event, ctx) => {
+    if (event.toolName === TOOL_NAME) {
+      runState.turnCalledTodo = true;
+      return;
+    }
+    if (!MUTATING_TOOL_NAMES.has(event.toolName)) {
+      return;
+    }
+
+    runState.turnMutated = true;
+    restore(ctx);
+    if (!shouldNudgePropose({ items: store.items, ...runState })) {
+      return;
+    }
+
+    runState.proposeNudgedThisRun = true;
+    sendSteer(
+      pi,
+      runState,
+      NUDGE_TYPE,
+      'Use sideroom_todo propose now to create the live board before continuing implementation.',
+    );
+  });
+
+  pi.on('turn_end', (_event, ctx) => {
+    restore(ctx);
+    if (!shouldWatchdogUpdate({ items: store.items, ...runState })) {
+      return;
+    }
+
+    runState.updateWatchdogThisTurn = true;
+    sendSteer(
+      pi,
+      runState,
+      WATCHDOG_TYPE,
+      'Use sideroom_todo update to reflect this work before continuing to the next item.',
+    );
+  });
+}
+
+function createTodoRunState(): TodoRunState {
+  return {
+    proposeNudgedThisRun: false,
+    updateWatchdogThisTurn: false,
+    turnMutated: false,
+    turnCalledTodo: false,
+    steerFromUs: false,
+  };
+}
+
+function resetTurnState(runState: TodoRunState): void {
+  runState.turnMutated = false;
+  runState.turnCalledTodo = false;
+  runState.updateWatchdogThisTurn = false;
+}
+
+function sendSteer(
+  pi: ExtensionAPI,
+  runState: TodoRunState,
+  customType: string,
+  content: string,
+): void {
+  runState.steerFromUs = true;
+  pi.sendMessage(
+    { customType, content, display: false },
+    { triggerTurn: true, deliverAs: 'steer' },
+  );
+}