@rmrdeveloper/sideroom-pi 5.0.0 → 6.0.1

package/extensions/todo/model.ts

@@ -0,0 +1,327 @@
+import { type Static, Type } from 'typebox';
+import { Check } from 'typebox/value';
+
+export const TOOL_NAME = 'sideroom_todo';
+export const UI_UNAVAILABLE =
+  'Error: UI not available (running in non-interactive mode)';
+export const TODO_ACTION = {
+  propose: 'propose',
+  update: 'update',
+} as const;
+export const TODO_STATUS = {
+  pending: 'pending',
+  inProgress: 'in_progress',
+  completed: 'completed',
+  cancelled: 'cancelled',
+} as const;
+
+const MAX_TODO_ITEMS = 20;
+const MAX_TODO_ID_LENGTH = 32;
+const MAX_TODO_CONTENT_LENGTH = 200;
+const STATUS_COLUMN_WIDTH = 12;
+
+const TodoStatusSchema = Type.Union([
+  Type.Literal(TODO_STATUS.pending),
+  Type.Literal(TODO_STATUS.inProgress),
+  Type.Literal(TODO_STATUS.completed),
+  Type.Literal(TODO_STATUS.cancelled),
+]);
+
+const TodoItemSchema = Type.Object({
+  id: Type.String({ description: 'Stable identifier for this item' }),
+  content: Type.String({ description: 'Short description of the work' }),
+  status: TodoStatusSchema,
+});
+
+const TodoPatchSchema = Type.Object({
+  id: Type.String({ description: 'Identifier of the item to patch' }),
+  status: Type.Optional(TodoStatusSchema),
+  content: Type.Optional(
+    Type.String({ description: 'Replacement work description' }),
+  ),
+});
+
+const ProposeParamsSchema = Type.Object({
+  action: Type.Literal(TODO_ACTION.propose),
+  items: Type.Array(TodoItemSchema, {
+    maxItems: MAX_TODO_ITEMS,
+    description: 'Replacement board, with at most 20 items',
+  }),
+});
+
+const UpdateParamsSchema = Type.Object({
+  action: Type.Literal(TODO_ACTION.update),
+  patches: Type.Array(TodoPatchSchema, {
+    minItems: 1,
+    description: 'Patches to apply together',
+  }),
+});
+
+export const TodoParamsSchema = Type.Union([
+  ProposeParamsSchema,
+  UpdateParamsSchema,
+]);
+
+export type TodoParams = Static<typeof TodoParamsSchema>;
+export type TodoAction = (typeof TODO_ACTION)[keyof typeof TODO_ACTION];
+export type TodoStatus = (typeof TODO_STATUS)[keyof typeof TODO_STATUS];
+
+export interface TodoItem {
+  readonly id: string;
+  readonly content: string;
+  readonly status: TodoStatus;
+}
+
+export interface TodoPatch {
+  readonly id: string;
+  readonly status?: TodoStatus;
+  readonly content?: string;
+}
+
+export type ParsedTodoParams =
+  | {
+      readonly action: typeof TODO_ACTION.propose;
+      readonly items: readonly TodoItem[];
+    }
+  | {
+      readonly action: typeof TODO_ACTION.update;
+      readonly patches: readonly TodoPatch[];
+    };
+
+export type ParseTodoResult =
+  | { readonly ok: true; readonly params: ParsedTodoParams }
+  | { readonly ok: false; readonly message: string };
+
+export type ApplyTodoResult =
+  | { readonly ok: true; readonly items: readonly TodoItem[] }
+  | { readonly ok: false; readonly message: string };
+
+export interface TodoGuardState {
+  readonly items: readonly TodoItem[];
+  readonly turnMutated: boolean;
+  readonly turnCalledTodo: boolean;
+  readonly proposeNudgedThisRun: boolean;
+  readonly updateWatchdogThisTurn: boolean;
+  readonly steerFromUs: boolean;
+}
+
+const STATUS_MARKS: Readonly<Record<TodoStatus, string>> = {
+  [TODO_STATUS.pending]: '-',
+  [TODO_STATUS.inProgress]: '>',
+  [TODO_STATUS.completed]: '✓',
+  [TODO_STATUS.cancelled]: '~',
+};
+
+const BOARD_INSTRUCTIONS =
+  'Call sideroom_todo update before the next item. While any item is pending, exactly one must be in_progress. Complete the current item and start the next in the same update. propose replaces the list; update patches by id.';
+
+export function parseTodoParams(value: unknown): ParseTodoResult {
+  if (!Check(TodoParamsSchema, value)) {
+    return { ok: false, message: 'Error: Invalid sideroom_todo parameters' };
+  }
+
+  if (value.action === TODO_ACTION.propose) {
+    const items = normalizeItems(value.items);
+    if (!items.ok) {
+      return { ok: false, message: items.message };
+    }
+    const invariant = validateBoard(items.items);
+    if (invariant !== undefined) {
+      return { ok: false, message: invariant };
+    }
+    return {
+      ok: true,
+      params: { action: TODO_ACTION.propose, items: items.items },
+    };
+  }
+
+  const patches = normalizePatches(value.patches);
+  if (!patches.ok) {
+    return { ok: false, message: patches.message };
+  }
+  return {
+    ok: true,
+    params: { action: TODO_ACTION.update, patches: patches.patches },
+  };
+}
+
+export function applyTodoParams(
+  items: readonly TodoItem[],
+  params: ParsedTodoParams,
+): ApplyTodoResult {
+  if (params.action === TODO_ACTION.propose) {
+    return { ok: true, items: params.items };
+  }
+
+  const patchesById = new Map(params.patches.map((patch) => [patch.id, patch]));
+  for (const id of patchesById.keys()) {
+    if (!items.some((item) => item.id === id)) {
+      return { ok: false, message: `Error: Unknown todo id: ${id}` };
+    }
+  }
+
+  const updated = items.map((item) => {
+    const patch = patchesById.get(item.id);
+    if (patch === undefined) {
+      return item;
+    }
+    return {
+      id: item.id,
+      content: patch.content ?? item.content,
+      status: patch.status ?? item.status,
+    };
+  });
+  const invariant = validateBoard(updated);
+  if (invariant !== undefined) {
+    return { ok: false, message: invariant };
+  }
+  return { ok: true, items: updated };
+}
+
+export function formatBoardBlock(items: readonly TodoItem[]): string {
+  const idWidth = Math.max(1, ...items.map((item) => item.id.length));
+  const rows = items.map(
+    (item) =>
+      `${STATUS_MARKS[item.status]} ${item.id.padEnd(idWidth)} ${item.status.padEnd(STATUS_COLUMN_WIDTH)} ${item.content}`,
+  );
+  return [
+    'sideroom_todo (live board; do not recap in prose)',
+    ...rows,
+    '',
+    BOARD_INSTRUCTIONS,
+  ].join('\n');
+}
+
+export function shouldNudgePropose(state: TodoGuardState): boolean {
+  return (
+    state.turnMutated &&
+    state.items.length === 0 &&
+    !state.proposeNudgedThisRun &&
+    !state.steerFromUs
+  );
+}
+
+export function shouldWatchdogUpdate(state: TodoGuardState): boolean {
+  return (
+    state.turnMutated &&
+    state.items.length > 0 &&
+    !state.turnCalledTodo &&
+    !state.updateWatchdogThisTurn &&
+    !state.steerFromUs
+  );
+}
+
+function normalizeItems(
+  items: readonly Static<typeof TodoItemSchema>[],
+):
+  | { readonly ok: true; readonly items: readonly TodoItem[] }
+  | { readonly ok: false; readonly message: string } {
+  const seen = new Set<string>();
+  const normalized: TodoItem[] = [];
+  for (const item of items) {
+    const id = normalizeId(item.id);
+    if (!id.ok) {
+      return id;
+    }
+    if (seen.has(id.value)) {
+      return { ok: false, message: `Error: Duplicate todo id: ${id.value}` };
+    }
+    seen.add(id.value);
+
+    const content = normalizeContent(item.content);
+    if (!content.ok) {
+      return content;
+    }
+    normalized.push({
+      id: id.value,
+      content: content.value,
+      status: item.status,
+    });
+  }
+  return { ok: true, items: normalized };
+}
+
+function normalizePatches(
+  patches: readonly Static<typeof TodoPatchSchema>[],
+):
+  | { readonly ok: true; readonly patches: readonly TodoPatch[] }
+  | { readonly ok: false; readonly message: string } {
+  const seen = new Set<string>();
+  const normalized: TodoPatch[] = [];
+  for (const patch of patches) {
+    const id = normalizeId(patch.id);
+    if (!id.ok) {
+      return id;
+    }
+    if (seen.has(id.value)) {
+      return {
+        ok: false,
+        message: `Error: Duplicate todo patch id: ${id.value}`,
+      };
+    }
+    seen.add(id.value);
+    if (patch.status === undefined && patch.content === undefined) {
+      return {
+        ok: false,
+        message: `Error: Todo patch '${id.value}' must change status or content`,
+      };
+    }
+
+    let content: string | undefined;
+    if (patch.content !== undefined) {
+      const normalizedContent = normalizeContent(patch.content);
+      if (!normalizedContent.ok) {
+        return normalizedContent;
+      }
+      content = normalizedContent.value;
+    }
+    normalized.push({ id: id.value, status: patch.status, content });
+  }
+  return { ok: true, patches: normalized };
+}
+
+function normalizeId(
+  value: string,
+):
+  | { readonly ok: true; readonly value: string }
+  | { readonly ok: false; readonly message: string } {
+  const normalized = value.trim();
+  if (normalized.length === 0 || normalized.length > MAX_TODO_ID_LENGTH) {
+    return {
+      ok: false,
+      message: `Error: Todo id must contain 1 to ${String(MAX_TODO_ID_LENGTH)} characters`,
+    };
+  }
+  return { ok: true, value: normalized };
+}
+
+function normalizeContent(
+  value: string,
+):
+  | { readonly ok: true; readonly value: string }
+  | { readonly ok: false; readonly message: string } {
+  const normalized = value.trim();
+  if (normalized.length === 0 || normalized.length > MAX_TODO_CONTENT_LENGTH) {
+    return {
+      ok: false,
+      message: `Error: Todo content must contain 1 to ${String(MAX_TODO_CONTENT_LENGTH)} characters`,
+    };
+  }
+  return { ok: true, value: normalized };
+}
+
+function validateBoard(items: readonly TodoItem[]): string | undefined {
+  const pendingCount = items.filter(
+    (item) => item.status === TODO_STATUS.pending,
+  ).length;
+  const inProgressCount = items.filter(
+    (item) => item.status === TODO_STATUS.inProgress,
+  ).length;
+  if (inProgressCount > 1) {
+    return 'Error: At most one todo item may be in_progress';
+  }
+  if (pendingCount > 0 && inProgressCount !== 1) {
+    return 'Error: A board with pending items must have exactly one in_progress item';
+  }
+  return undefined;
+}

package/extensions/todo/session.ts

@@ -0,0 +1,166 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import {
+  formatBoardBlock,
+  parseTodoParams,
+  TODO_ACTION,
+  TOOL_NAME,
+  type TodoItem,
+} from './model.ts';
+import { renderTodoWidget } from './ui.ts';
+
+export const SNAPSHOT_TYPE = 'sideroom-todo';
+export const WIDGET_KEY = 'sideroom-todo';
+export const TODO_WIDGET_REFRESH_EVENT = 'sideroom:todo-widget-refreshed';
+
+export interface TodoStore {
+  items: readonly TodoItem[];
+}
+
+export type BoardLifecycle = (ctx: ExtensionContext) => void;
+
+type SessionBranch = ReturnType<
+  ExtensionContext['sessionManager']['getBranch']
+>;
+
+export function createTodoStore(items: readonly TodoItem[] = []): TodoStore {
+  return { items };
+}
+
+export function reconstructTodoItems(
+  branch: SessionBranch,
+): readonly TodoItem[] {
+  const snapshotItems = findSnapshotItems(branch);
+  if (snapshotItems !== undefined) {
+    return snapshotItems;
+  }
+  return findToolResultItems(branch) ?? [];
+}
+
+export function restoreBoard(
+  store: TodoStore,
+  ctx: Pick<ExtensionContext, 'sessionManager'>,
+): void {
+  store.items = reconstructTodoItems(ctx.sessionManager.getBranch());
+}
+
+export function persistSnapshot(
+  pi: Pick<ExtensionAPI, 'appendEntry'>,
+  items: readonly TodoItem[],
+): void {
+  pi.appendEntry(SNAPSHOT_TYPE, { items });
+}
+
+export function refreshBoard(
+  store: TodoStore,
+  ctx: Pick<ExtensionContext, 'ui'>,
+): void {
+  if (store.items.length === 0) {
+    ctx.ui.setWidget(WIDGET_KEY, undefined);
+    return;
+  }
+  ctx.ui.setWidget(WIDGET_KEY, (_tui, theme) => {
+    const lines = renderTodoWidget(store.items, theme);
+    return new Text(lines?.join('\n') ?? '', 0, 0);
+  });
+}
+
+export function restoreAndRefreshBoard(
+  store: TodoStore,
+  ctx: ExtensionContext,
+): void {
+  restoreBoard(store, ctx);
+  refreshBoard(store, ctx);
+}
+
+export function commitBoard(
+  store: TodoStore,
+  pi: Pick<ExtensionAPI, 'appendEntry'>,
+  ctx: Pick<ExtensionContext, 'ui'>,
+  items: readonly TodoItem[],
+): void {
+  store.items = items;
+  persistSnapshot(pi, items);
+  refreshBoard(store, ctx);
+}
+
+export function registerSessionRefreshEvents(
+  pi: ExtensionAPI,
+  restoreAndRefresh: BoardLifecycle,
+): void {
+  pi.on('session_start', (_event, ctx) => restoreAndRefresh(ctx));
+  pi.on('session_tree', (_event, ctx) => restoreAndRefresh(ctx));
+  pi.on('session_compact', (_event, ctx) => restoreAndRefresh(ctx));
+}
+
+export function registerBoardContext(
+  pi: ExtensionAPI,
+  store: TodoStore,
+  restoreAndRefresh: BoardLifecycle,
+): void {
+  pi.on('before_agent_start', (event, ctx) => {
+    restoreAndRefresh(ctx);
+    if (store.items.length === 0) {
+      return;
+    }
+    return {
+      systemPrompt: `${event.systemPrompt}\n\n${formatBoardBlock(store.items)}`,
+    };
+  });
+}
+
+function findSnapshotItems(
+  branch: SessionBranch,
+): readonly TodoItem[] | undefined {
+  for (let index = branch.length - 1; index >= 0; index -= 1) {
+    const entry = branch[index];
+    if (entry?.type === 'custom' && entry.customType === SNAPSHOT_TYPE) {
+      const items = readSnapshot(entry.data);
+      if (items !== undefined) {
+        return items;
+      }
+    }
+  }
+  return undefined;
+}
+
+function findToolResultItems(
+  branch: SessionBranch,
+): readonly TodoItem[] | undefined {
+  for (let index = branch.length - 1; index >= 0; index -= 1) {
+    const entry = branch[index];
+    if (entry?.type !== 'message') {
+      continue;
+    }
+    const message = entry.message;
+    if (message.role !== 'toolResult' || message.toolName !== TOOL_NAME) {
+      continue;
+    }
+    const items = readSnapshot(message.details);
+    if (items !== undefined) {
+      return items;
+    }
+  }
+  return undefined;
+}
+
+function readSnapshot(value: unknown): readonly TodoItem[] | undefined {
+  if (!isRecord(value) || !Array.isArray(value.items)) {
+    return undefined;
+  }
+  const parsed = parseTodoParams({
+    action: TODO_ACTION.propose,
+    items: value.items,
+  });
+  if (!parsed.ok || parsed.params.action !== TODO_ACTION.propose) {
+    return undefined;
+  }
+  return parsed.params.items;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/extensions/todo/ui.ts

@@ -0,0 +1,41 @@
+import type { Theme } from '@earendil-works/pi-coding-agent';
+import { formatBoardBlock, TODO_STATUS, type TodoItem } from './model.ts';
+
+export function renderTodoWidget(
+  items: readonly TodoItem[],
+  theme: Theme,
+): string[] | undefined {
+  if (items.length === 0) {
+    return undefined;
+  }
+
+  const active = items.filter(
+    (item) => item.status === TODO_STATUS.inProgress,
+  ).length;
+  const queued = items.filter(
+    (item) => item.status === TODO_STATUS.pending,
+  ).length;
+  const blockLines = formatBoardBlock(items).split('\n');
+  const rows = blockLines.slice(1, 1 + items.length);
+  const header = theme.fg(
+    'accent',
+    theme.bold(
+      `Sideroom board (${String(active)} active, ${String(queued)} queued)`,
+    ),
+  );
+  const renderedRows = rows.map((row, index) => {
+    const item = items[index];
+    if (item === undefined) {
+      return row;
+    }
+    if (item.status === TODO_STATUS.inProgress) {
+      return theme.fg('success', row);
+    }
+    if (item.status === TODO_STATUS.pending) {
+      return theme.fg('text', row);
+    }
+    return theme.fg('muted', row);
+  });
+
+  return [header, ...renderedRows];
+}

package/package.json

@@ -1,41 +1,40 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "5.0.0",
-  "description": "A global Pi package that runs an isolated coding-agent pipeline through /sideroom.",
+  "version": "6.0.1",
+  "description": "A global Pi package with a questionnaire, work board, and edited-file view for parent agents.",
   "type": "module",
   "files": [
-    "dist",
-    "src/assets",
-    "skills"
+    "extensions",
+    "assets",
+    "!extensions/**/*.test.ts"
   ],
   "scripts": {
-    "build": "esbuild src/pi-extension.ts --bundle --platform=node --format=esm --outfile=dist/pi-extension.js --packages=external",
-    "prepublishOnly": "npm run check && npm run build",
+    "prepublishOnly": "npm run check",
     "changeset": "changeset",
     "changeset:status": "changeset status",
     "version-packages": "changeset version",
-    "release": "npm run check && changeset publish",
     "commitlint": "commitlint",
     "types": "tsc --noEmit",
-    "test": "node --test src/core/agents.test.ts src/core/catalog.test.ts src/core/findings.test.ts src/core/grilling.test.ts src/core/orchestrator.test.ts src/pi-command.test.ts src/runtimes/pi.test.ts",
-    "lint": "biome lint src commitlint.config.mjs",
-    "lint:fix": "biome lint --write src commitlint.config.mjs",
-    "format": "biome format --write src package.json biome.json commitlint.config.mjs .changeset/config.json",
-    "format:check": "biome format src package.json biome.json commitlint.config.mjs .changeset/config.json",
-    "check": "npm run types && biome check src package.json biome.json commitlint.config.mjs .changeset/config.json && npm test"
+    "test": "node --test 'extensions/**/*.test.ts'",
+    "lint": "biome lint extensions scripts commitlint.config.mjs",
+    "lint:fix": "biome lint --write extensions scripts commitlint.config.mjs",
+    "format": "biome format --write extensions scripts package.json biome.json commitlint.config.mjs .changeset/config.json",
+    "format:check": "biome format extensions scripts package.json biome.json commitlint.config.mjs .changeset/config.json",
+    "check:if-blocks": "node scripts/check-if-blocks.mjs",
+    "check": "npm run types && npm run check:if-blocks && biome check extensions scripts package.json biome.json commitlint.config.mjs .changeset/config.json && npm test"
   },
   "engines": {
     "node": ">=22.19.0"
   },
   "keywords": [
-    "agents",
-    "ai",
-    "coding-agents",
-    "multi-agent",
-    "orchestration",
     "pi",
     "pi-package",
-    "pi-sdk",
+    "pi-extension",
+    "questionnaire",
+    "todo",
+    "edited-files",
+    "sideroom_ask",
+    "sideroom_todo",
     "typescript"
   ],
   "license": "MIT",
@@ -48,23 +47,23 @@
   },
   "pi": {
     "extensions": [
-      "./dist/pi-extension.js"
-    ],
-    "skills": [
-      "./skills"
+      "./extensions"
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.4",
     "@biomejs/biome": "2.5.11",
     "@changesets/cli": "^3.0.2",
     "@commitlint/cli": "^21.2.2",
     "@commitlint/config-conventional": "^21.2.2",
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-tui": "0.84.4",
     "@types/node": "^22.20.1",
-    "esbuild": "^0.25.0",
+    "typebox": "1.3.7",
     "typescript": "^5.6.0"
   }
 }