@rmrdeveloper/sideroom-pi 5.0.0 → 6.0.1

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' },
+  );
+}

package/extensions/todo/index.ts

@@ -0,0 +1,91 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { executeTodo, type TodoToolDetails } from './execute.ts';
+import { registerGuardEvents } from './guards.ts';
+import { TOOL_NAME, TodoParamsSchema } from './model.ts';
+import {
+  type BoardLifecycle,
+  commitBoard,
+  createTodoStore,
+  registerBoardContext,
+  registerSessionRefreshEvents,
+  restoreAndRefreshBoard,
+  restoreBoard,
+  TODO_WIDGET_REFRESH_EVENT,
+  type TodoStore,
+} from './session.ts';
+
+export const TODO_DESCRIPTION =
+  'Maintain a live, user-visible work board. propose replaces the full board; update patches existing items by id.';
+
+export const TODO_PROMPT_SNIPPET =
+  'Maintain the live work board with propose and update.';
+
+export const TODO_PROMPT_GUIDELINES = [
+  'Use sideroom_todo to maintain a live work board when implementation has more than one step.',
+  'Use propose to replace the board and update to patch item ids. While any item is pending, exactly one must be in_progress.',
+  'Complete the current item and start the next item in the same update call.',
+  'propose is interactive-TUI-only; update also works in print, JSON, and RPC modes.',
+];
+
+// Pi loads extensions/*/index.ts through export default.
+export default function registerTodo(pi: ExtensionAPI): void {
+  const store = createTodoStore();
+  const restore: BoardLifecycle = (ctx) => {
+    restoreBoard(store, ctx);
+  };
+  const notifyWidgetRefresh: BoardLifecycle = (ctx) => {
+    pi.events.emit(TODO_WIDGET_REFRESH_EVENT, ctx);
+  };
+  const restoreAndRefresh: BoardLifecycle = (ctx) => {
+    restoreAndRefreshBoard(store, ctx);
+    notifyWidgetRefresh(ctx);
+  };
+
+  registerSessionRefreshEvents(pi, restoreAndRefresh);
+  registerGuardEvents(pi, store, restore);
+  registerBoardContext(pi, store, restoreAndRefresh);
+  registerTodoTool(pi, store, notifyWidgetRefresh);
+}
+
+function registerTodoTool(
+  pi: ExtensionAPI,
+  store: TodoStore,
+  notifyWidgetRefresh: BoardLifecycle,
+): void {
+  pi.registerTool({
+    name: TOOL_NAME,
+    label: 'Sideroom Todo',
+    description: TODO_DESCRIPTION,
+    promptSnippet: TODO_PROMPT_SNIPPET,
+    promptGuidelines: TODO_PROMPT_GUIDELINES,
+    parameters: TodoParamsSchema,
+    executionMode: 'sequential',
+    execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {
+      const result = executeTodo(params, ctx, store.items);
+      if (result.details.error !== undefined) {
+        return result;
+      }
+
+      commitBoard(store, pi, ctx, result.details.items);
+      notifyWidgetRefresh(ctx);
+      return result;
+    },
+    renderCall(args, theme) {
+      const text = `${theme.fg('toolTitle', theme.bold(`${TOOL_NAME} `))}${theme.fg('muted', args.action)}`;
+      return new Text(text, 0, 0);
+    },
+    renderResult(result, _options, theme) {
+      const details = result.details as TodoToolDetails | undefined;
+      if (details?.error !== undefined) {
+        return new Text(theme.fg('error', details.error), 0, 0);
+      }
+      const text = result.content[0];
+      return new Text(
+        theme.fg('success', text?.type === 'text' ? text.text : ''),
+        0,
+        0,
+      );
+    },
+  });
+}