@rmrdeveloper/sideroom-pi 9.0.1 → 9.2.0

package/extensions/rules/checks.ts

@@ -39,9 +39,6 @@ const DEBUG_PATTERNS: readonly RegExp[] = [
   /\bdbg!\s*\(/,
 ];
 
-// Keep these patterns on syntax that can only introduce a type. Value-level
-// commas, assignments, and operators may legally surround an identifier named
-// `any`, so they are deliberately absent.
 const EXPLICIT_ANY_PATTERNS: readonly RegExp[] = [
   /\bas\s+any\b/,
   /\b(?:keyof|satisfies)\s+any\b/,
@@ -54,8 +51,6 @@ const EXPLICIT_ANY_PATTERNS: readonly RegExp[] = [
   /^\s*(?:(?:public|private|protected|readonly|static|declare|abstract)\s+)*[$\w]+[?!]?\s*:\s*(?:(?:=>)|[^;,=\n])*\bany\b[^;=\n]*(?:;|=)/,
 ];
 
-// A suppression is a comment whose first token is the directive; prose that
-// mentions the directive, or a string that quotes it, is not one.
 const SUPPRESSED_TYPE_ERRORS =
   /(?:^|\s)(?:\/\/|\/\*)\s*@ts-(?:ignore|nocheck)\b/;
 

package/extensions/rules/index.ts

@@ -5,7 +5,6 @@ import {
   resetRulesState,
 } from './guard.ts';
 
-// Pi loads extensions/*/index.ts through export default.
 export default function registerRules(pi: ExtensionAPI): void {
   const state = createRulesState();
   registerRulesGuard(pi, state);

package/extensions/rules/lexer.ts

@@ -10,7 +10,7 @@ const LEXICAL_MODE = {
 type LexicalMode = (typeof LEXICAL_MODE)[keyof typeof LEXICAL_MODE];
 
 export interface MaskOptions {
-  /** Keep comment text so a caller can read the directives inside it. */
+
   readonly keepComments?: boolean;
 }
 

package/extensions/shared/check-status.ts

@@ -0,0 +1,35 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from '@earendil-works/pi-coding-agent';
+
+const CHECK_STATUS_EVENT = 'sideroom:check-status';
+
+export interface CheckStatus {
+  readonly command: string;
+  readonly green: boolean;
+}
+
+interface CheckStatusRequest {
+  readonly ctx: ExtensionContext;
+  status: CheckStatus | undefined;
+}
+
+export function registerCheckStatus(
+  pi: ExtensionAPI,
+  resolve: (ctx: ExtensionContext) => CheckStatus | undefined,
+): void {
+  pi.events.on(CHECK_STATUS_EVENT, (payload) => {
+    const request = payload as CheckStatusRequest;
+    request.status = resolve(request.ctx);
+  });
+}
+
+export function readCheckStatus(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): CheckStatus | undefined {
+  const request: CheckStatusRequest = { ctx, status: undefined };
+  pi.events.emit(CHECK_STATUS_EVENT, request);
+  return request.status;
+}

package/extensions/shared/file-path.ts

@@ -10,7 +10,6 @@ const MISSING_PATH_ERROR_CODE = {
 } as const;
 const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
 
-// File guards must resolve the model's path exactly as Pi's built-in tools do.
 export function resolveFileToolPath(
   cwd: string,
   path: string,
@@ -29,8 +28,6 @@ export function resolveFileToolPath(
   return realpathOr(absolutePath);
 }
 
-// A file that does not exist yet keeps its unresolved path, so it is matched
-// against the literal working directory as well as the canonical one.
 export function projectRelativePath(
   cwd: string,
   absolutePath: string,

package/extensions/shared/read-file.ts

@@ -1,7 +1,5 @@
 import { readFileSync } from 'node:fs';
 
-// A missing file is an expected answer to "what was there before", not a
-// failure. Anything else about the read is a real problem and surfaces.
 export function readFileIfExists(path: string): string | undefined {
   try {
     return readFileSync(path, 'utf8');

package/extensions/shared/settle.ts

@@ -10,8 +10,59 @@ import type {
 const COMPLETED_OUTCOME = 'completed';
 const CUSTOM_MESSAGE_ENTRY = 'custom_message';
 const SETTLE_PRIORITY_EVENT = 'sideroom:settle-priority';
+const SETTLE_SUPPLEMENT_EVENT = 'sideroom:settle-supplement';
+const SETTLE_WAIT_EVENT = 'sideroom:settle-wait';
 
-export const SETTLE_PRIORITY = { review: 0, done: 1, explain: 2 } as const;
+interface SettleWaitRequest {
+  readonly ctx: ExtensionContext;
+  readonly waits: Promise<void>[];
+}
+
+export function registerSettleWait(
+  pi: ExtensionAPI,
+  wait: (ctx: ExtensionContext) => Promise<void>,
+): void {
+  pi.events.on(SETTLE_WAIT_EVENT, (payload) => {
+    const request = payload as SettleWaitRequest;
+    request.waits.push(wait(request.ctx));
+  });
+  pi.on('agent_before_settle', async (event, ctx) => {
+    if (acceptsSettleSteer(event)) {
+      await wait(ctx);
+    }
+  });
+}
+
+async function waitForSettle(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+  const request: SettleWaitRequest = { ctx, waits: [] };
+  pi.events.emit(SETTLE_WAIT_EVENT, request);
+  await Promise.all(request.waits);
+}
+
+export const SETTLE_PRIORITY = { review: 0, persona: 1 } as const;
+
+interface SettleSupplement {
+  readonly customType: string;
+  readonly content: string;
+}
+
+interface SettleSupplementRequest {
+  readonly ctx: ExtensionContext;
+  readonly messages: SettleSupplement[];
+}
+
+export function registerSettleSupplement(
+  pi: ExtensionAPI,
+  prepare: (ctx: ExtensionContext) => SettleSupplement | undefined,
+): void {
+  pi.events.on(SETTLE_SUPPLEMENT_EVENT, (payload) => {
+    const request = payload as SettleSupplementRequest;
+    const message = prepare(request.ctx);
+    if (message !== undefined) {
+      request.messages.push(message);
+    }
+  });
+}
 
 interface SettlePriorityRequest {
   readonly ctx: ExtensionContext;
@@ -31,8 +82,6 @@ const USER_INPUT_SOURCES: ReadonlySet<InputSource> = new Set([
   'rpc',
 ]);
 
-// A message typed while the agent runs joins the current run as a steer or
-// follow-up; only input that arrives idle opens a new turn.
 export function startsUserTurn(event: InputEvent): boolean {
   return (
     USER_INPUT_SOURCES.has(event.source) &&
@@ -40,8 +89,6 @@ export function startsUserTurn(event: InputEvent): boolean {
   );
 }
 
-// Any queued message or an earlier handler's continuation still has work to
-// run. Yield without consuming the guard's state until a quiet boundary.
 export function acceptsSettleSteer(event: AgentBeforeSettleEvent): boolean {
   return (
     event.outcome === COMPLETED_OUTCOME &&
@@ -50,9 +97,6 @@ export function acceptsSettleSteer(event: AgentBeforeSettleEvent): boolean {
   );
 }
 
-// Pi gives each extension its own API object. Its synchronous event bus is
-// shared, so ask which stages are pending rather than relying on load order
-// or module-global state that would leak across sessions and reloads.
 export function registerSettleGuard(
   pi: ExtensionAPI,
   guard: SettleGuard,
@@ -64,8 +108,12 @@ export function registerSettleGuard(
     }
   });
 
-  pi.on('agent_before_settle', (event, ctx) => {
-    if (!acceptsSettleSteer(event) || !guard.pending(ctx)) {
+  pi.on('agent_before_settle', async (event, ctx) => {
+    if (!acceptsSettleSteer(event)) {
+      return;
+    }
+    await waitForSettle(pi, ctx);
+    if (ctx.signal?.aborted || ctx.hasPendingMessages() || !acceptsSettleSteer(event) || !guard.pending(ctx)) {
       return;
     }
     const request: SettlePriorityRequest = { ctx, priorities: new Set() };
@@ -73,12 +121,29 @@ export function registerSettleGuard(
     if ([...request.priorities].some((priority) => priority < guard.priority)) {
       return;
     }
-    return guard.handle(event, ctx);
+    const continuation = guard.handle(event, ctx);
+    if (!continuation?.continue) {
+      return continuation;
+    }
+    const supplements: SettleSupplementRequest = { ctx, messages: [] };
+    pi.events.emit(SETTLE_SUPPLEMENT_EVENT, supplements);
+    return {
+      ...continuation,
+      entries: [
+        ...(continuation.entries ?? event.entries),
+        ...supplements.messages.map(
+          (message) =>
+            ({
+              type: CUSTOM_MESSAGE_ENTRY,
+              ...message,
+              display: false,
+            }) as const,
+        ),
+      ],
+    };
   });
 }
 
-// Handlers chain on agent_before_settle, so keep the entries earlier handlers
-// proposed; replacing them would drop another extension's steer.
 interface HiddenSteerOptions {
   readonly event: AgentBeforeSettleEvent;
   readonly customType: string;

package/extensions/todo/guards.ts

@@ -1,109 +1,65 @@
-import type {
-  ExtensionAPI,
-  ExtensionContext,
-} from '@earendil-works/pi-coding-agent';
 import {
-  shouldNudgePropose,
-  shouldWatchdogUpdate,
-  TOOL_NAME,
-} from './model.ts';
+  type ExtensionAPI,
+  type ExtensionContext,
+  isEditToolResult,
+  isWriteToolResult,
+} from '@earendil-works/pi-coding-agent';
+import { startsUserTurn } from '../shared/settle.ts';
+import { TODO_STATUS } 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;
-}
+const REMINDER_TYPE = 'sideroom-todo-reminder';
 
 export function registerGuardEvents(
   pi: ExtensionAPI,
   store: TodoStore,
   restore: (ctx: ExtensionContext) => void,
 ): void {
-  const runState = createTodoRunState();
+  let remindedThisTurn = false;
 
   pi.on('input', (event) => {
-    if (event.source === 'interactive' || event.source === 'rpc') {
-      runState.proposeNudgedThisRun = false;
-      runState.steerFromUs = false;
+    if (startsUserTurn(event)) {
+      remindedThisTurn = false;
     }
   });
+  pi.on('session_start', () => {
+    remindedThisTurn = false;
+  });
 
-  pi.on('turn_start', () => resetTurnState(runState));
-
-  pi.on('tool_execution_start', (event, ctx) => {
-    if (event.toolName === TOOL_NAME) {
-      runState.turnCalledTodo = true;
+  pi.on('tool_result', (event, ctx) => {
+    if (
+      remindedThisTurn ||
+      event.isError ||
+      (!isWriteToolResult(event) && !isEditToolResult(event))
+    ) {
       return;
     }
-    if (!MUTATING_TOOL_NAMES.has(event.toolName)) {
-      return;
-    }
-
-    runState.turnMutated = true;
     restore(ctx);
-    if (!shouldNudgePropose({ items: store.items, ...runState })) {
+    if (store.items.length === 0 && ctx.mode !== 'tui') {
       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 })) {
+    if (
+      store.items.length > 0 &&
+      !store.items.some(
+        (item) =>
+          item.status === TODO_STATUS.pending ||
+          item.status === TODO_STATUS.inProgress,
+      )
+    ) {
       return;
     }
 
-    runState.updateWatchdogThisTurn = true;
-    sendSteer(
-      pi,
-      runState,
-      WATCHDOG_TYPE,
-      'Use sideroom_todo update to reflect this work before continuing to the next item.',
+    remindedThisTurn = true;
+    pi.sendMessage(
+      {
+        customType: REMINDER_TYPE,
+        content:
+          store.items.length === 0
+            ? 'Use sideroom_todo propose if this implementation has multiple steps. Maintain the board at task milestones, not after every tool call.'
+            : 'Update sideroom_todo when a task changes status, combining completion and the next task in one call. Do not update merely because a tool ran.',
+        display: false,
+      },
+      { triggerTurn: false, deliverAs: 'steer' },
     );
   });
 }
-
-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;
-  // A steer only silences the turn that sent it; later turns may steer again.
-  runState.steerFromUs = 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

@@ -29,13 +29,12 @@ export const TODO_PROMPT_SNIPPET =
 export const TODO_PROMPT_GUIDELINES = [
   'Use sideroom_todo to maintain a live work board when implementation has more than one step.',
   '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.',
+  'Update at task milestones, not after each tool call. 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.',
 ];
 
 const BOARD_SHORTCUT = 'f9';
 
-// Pi loads extensions/*/index.ts through export default.
 export default function registerTodo(pi: ExtensionAPI): void {
   const store = createTodoStore();
   const overlay = createTodoBoardOverlayController(() => store.items);

package/extensions/todo/model.ts

@@ -66,25 +66,11 @@ const UpdateParamsSchema = Type.Object({
   patches: TodoPatchesField,
 });
 
-/**
- * Strict validator and types for sideroom_todo arguments. Kept as a
- * discriminated union so invalid action/field combinations are rejected
- * exactly. This schema is not registered with Pi; see
- * TodoToolParametersSchema.
- */
 export const TodoParamsSchema = Type.Union([
   ProposeParamsSchema,
   UpdateParamsSchema,
 ]);
 
-/**
- * Tool-facing schema registered with Pi. It must stay a top-level object:
- * Claude Code silently drops every tool of an MCP server when one tool's
- * inputSchema has a non-object top level (anyOf/oneOf/allOf), which is exactly
- * what TodoParamsSchema emits. The discriminated union is still enforced at
- * runtime by parseTodoParams. See docs/extensions/todo.md ("Tool schema
- * compatibility") for the bug references and the condition to revert.
- */
 export const TodoToolParametersSchema = Type.Object({
   action: TodoActionSchema,
   items: Type.Optional(TodoItemsField),
@@ -110,13 +96,13 @@ export interface TodoPatch {
 
 export type ParsedTodoParams =
   | {
-      readonly action: typeof TODO_ACTION.propose;
-      readonly items: readonly TodoItem[];
-    }
+    readonly action: typeof TODO_ACTION.propose;
+    readonly items: readonly TodoItem[];
+  }
   | {
-      readonly action: typeof TODO_ACTION.update;
-      readonly patches: readonly TodoPatch[];
-    };
+    readonly action: typeof TODO_ACTION.update;
+    readonly patches: readonly TodoPatch[];
+  };
 
 export type ParseTodoResult =
   | { readonly ok: true; readonly params: ParsedTodoParams }
@@ -126,15 +112,6 @@ 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]: '>',
@@ -293,25 +270,6 @@ export function formatBoardBlock(items: readonly TodoItem[]): string {
   ].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>[],
 ):

package/extensions/todo/session.ts

@@ -94,8 +94,7 @@ export function registerSessionRefreshEvents(
   store: TodoStore,
   restoreAndRefresh: BoardLifecycle,
 ): void {
-  // A restore can drop the sent block from the model's context, so an unchanged
-  // board still has to be announced again.
+
   const restoreSession = (ctx: ExtensionContext) => {
     restoreAndRefresh(ctx);
     forgetSentBoardBlock(store);
@@ -132,8 +131,6 @@ export function registerBoardContext(
   });
 }
 
-// The block rides a session message instead of the system prompt: a volatile
-// system prompt invalidates the cached prefix of the whole request.
 function pendingBoardBlock(store: TodoStore): string | undefined {
   if (store.items.length === 0) {
     return undefined;

package/extensions/visual-context/broker.ts

@@ -176,17 +176,17 @@ export async function startBroker({
               delivery.browser,
               typeof message.error === 'string' || stale
                 ? {
-                    type: MESSAGE_TYPE.error,
-                    id: delivery.id,
-                    message: stale
-                      ? 'The session changed. Select the element again.'
-                      : String(message.error).slice(0, 500),
-                  }
+                  type: MESSAGE_TYPE.error,
+                  id: delivery.id,
+                  message: stale
+                    ? 'The session changed. Select the element again.'
+                    : String(message.error).slice(0, 500),
+                }
                 : {
-                    type: MESSAGE_TYPE.received,
-                    id: delivery.id,
-                    candidates: message.candidates,
-                  },
+                  type: MESSAGE_TYPE.received,
+                  id: delivery.id,
+                  candidates: message.candidates,
+                },
             );
             return;
           }

package/extensions/visual-context/configure.ts

@@ -102,8 +102,8 @@ function staticObject(expression: unknown, document: Document): ConfigObject {
             entry.type === 'ExportNamedDeclaration' ? entry.declaration : entry;
           return statement?.type === 'VariableDeclaration'
             ? statement.declarations.flatMap((item) =>
-                item === declaration ? [] : [item.init],
-              )
+              item === declaration ? [] : [item.init],
+            )
             : [];
         });
         if (
@@ -338,7 +338,7 @@ export function configureSource({
     if (value.start === null || value.start === undefined) {
       throw new Error('The plugin array location is unavailable.');
     }
-    // Inspect original markup before framework plugins erase its source positions.
+
     replacements.push({
       start: value.start + 1,
       end: value.start + 1,
@@ -415,7 +415,7 @@ export function configureSource({
       replacement.text +
       configured.slice(replacement.end);
   }
-  // Reject a broken patch before the parent agent receives a configuration edit.
+
   parse(configured, { sourceType: 'unambiguous', plugins: ['typescript'] });
   return { source: configured };
 }

package/extensions/visual-context/files.ts

@@ -67,8 +67,6 @@ export interface VisualPathPolicy {
   readonly allowedPath: (path: string) => string | undefined;
 }
 
-// Reuse ignore rules only within one synchronous operation. File metadata is
-// always read again: a remembered path must not authorize a replacement symlink.
 export function createPathPolicy(cwd: string): VisualPathPolicy {
   const root = realpathSync(cwd);
   const policies = new Map<
@@ -133,7 +131,6 @@ export function createPathPolicy(cwd: string): VisualPathPolicy {
   }
 }
 
-// Browser paths are untrusted, including paths reported by compiler plugins.
 export function allowedPath(cwd: string, path: string): string | undefined {
   return createPathPolicy(cwd).allowedPath(path);
 }

package/extensions/visual-context/index.ts

@@ -71,7 +71,7 @@ export default function registerVisualContext(
     commitPending({ store, pi, pending });
     refresh(ctx);
   };
-  // An async dialog may only act while it still belongs to the active session.
+
   const dialogIsCurrent = (ctx: ExtensionContext, epoch: number): boolean =>
     epoch === generation && activeContext === ctx;
   async function activate(ctx: ExtensionContext): Promise<void> {
@@ -191,8 +191,7 @@ export default function registerVisualContext(
       images: event.images,
     };
   });
-  // Input precedes model/auth validation in Pi. Keep the pending snapshot until
-  // the run actually starts so a failed submission cannot lose the attachment.
+
   pi.on('before_agent_start', (event, ctx) => {
     const attachment = preparedContext;
     preparedContext = undefined;
@@ -304,13 +303,13 @@ export default function registerVisualContext(
         const pending =
           selected.action === 'remove'
             ? store.pending.filter(
-                (item) => item.selection.id !== entry.selection.id,
-              )
+              (item) => item.selection.id !== entry.selection.id,
+            )
             : store.pending.map((item) =>
-                item.selection.id === entry.selection.id
-                  ? { ...item, chosen: candidate }
-                  : item,
-              );
+              item.selection.id === entry.selection.id
+                ? { ...item, chosen: candidate }
+                : item,
+            );
         savePending(ctx, pending);
       } finally {
         opening = false;

package/extensions/visual-context/literal.ts

@@ -13,7 +13,6 @@ export function isBabelSyntaxError(cause: unknown): boolean {
   );
 }
 
-// Only syntax literals are read. No inspected source is imported or executed.
 export function literalText(expression: string): string | undefined {
   let node: ReturnType<typeof parseExpression>;
   try {

package/extensions/visual-context/markup.ts

@@ -12,9 +12,9 @@ export type SourceNode =
   | SourceElement
   | { readonly kind: 'text'; readonly value: string }
   | {
-      readonly kind: 'group' | 'dynamic';
-      readonly children: readonly SourceNode[];
-    };
+    readonly kind: 'group' | 'dynamic';
+    readonly children: readonly SourceNode[];
+  };
 
 export interface ParsedMarkup {
   readonly nodes: readonly SourceNode[];
@@ -81,8 +81,6 @@ interface ElementRangeInput {
   readonly tag: string;
 }
 
-// Parsers may recover malformed syntax or omit locations. Such nodes must not
-// silently become source claims, even if their descriptors look convincing.
 export function verifiedElementRange({
   source,
   start,

package/extensions/visual-context/model.ts

@@ -118,9 +118,9 @@ export interface SourceCandidate {
 
 export interface SourceResolution {
   readonly candidates: readonly SourceCandidate[];
-  // A limit or unparseable file left the search incomplete; no match is not proof of absence.
+
   readonly truncated: boolean;
-  // More matches existed than the candidate cap lists.
+
   readonly capped: boolean;
   readonly issue?: string;
 }