@rmrdeveloper/sideroom-pi 9.0.0 → 9.1.0

package/extensions/jev/guard.ts

@@ -13,7 +13,8 @@ import {
 } from '../shared/file-path.ts';
 import { readFileIfExists } from '../shared/read-file.ts';
 import { REVIEW_NOTE_EVENT, type ReviewNote } from '../shared/review-note.ts';
-import { startsUserTurn } from '../shared/settle.ts';
+import { registerSettleWait, startsUserTurn } from '../shared/settle.ts';
+import { JevReviewQueue } from './queue.ts';
 import {
   askJevRequest,
   JEV_FAILURE,
@@ -78,6 +79,7 @@ export interface JevGuardState {
   rateLimitedThisTurn: boolean;
   lastModel: string | undefined;
   calls: number;
+  readonly queue: JevReviewQueue;
   readonly evidence: WorkflowEvidence;
   readonly pending: Map<string, PendingMutation>;
   readonly notedThisTurn: Set<string>;
@@ -96,23 +98,23 @@ export function createJevGuardState(): JevGuardState {
     rateLimitedThisTurn: false,
     lastModel: undefined,
     calls: 0,
+    queue: new JevReviewQueue(),
     evidence: createWorkflowEvidence(),
     pending: new Map(),
     notedThisTurn: new Set(),
   };
 }
 
-// The F10 screen calls this after the user stores a key or asks to retry.
 export function resetJevGuard(state: JevGuardState): void {
+  state.queue.cancel();
   resetWorkflowEvidence(state.evidence);
   state.halted = undefined;
   state.transientFailures = 0;
   state.rateLimitedThisTurn = false;
 }
 
-// Usage and per-turn memory belong to the active session: a new session starts
-// counting from zero. The breaker stays, because it tracks the key.
 export function resetJevSession(state: JevGuardState): void {
+  state.queue.cancel();
   resetWorkflowEvidence(state.evidence);
   state.calls = 0;
   state.rateLimitedThisTurn = false;
@@ -145,23 +147,23 @@ export function registerJevGuard(
   state: JevGuardState,
   dependencies: JevGuardDependencies,
 ): void {
+  registerSettleWait(pi, () => state.queue.drain());
+  pi.on('session_shutdown', () => state.queue.cancel());
+
   pi.on('input', (event) => {
     if (!startsUserTurn(event)) {
       return;
     }
+    state.queue.cancel();
     resetWorkflowEvidence(state.evidence);
     state.notedThisTurn.clear();
     state.rateLimitedThisTurn = false;
   });
 
-  // A call another extension blocks in tool_call never reaches tool_result,
-  // and every result of a turn lands before its turn_end.
   pi.on('turn_end', () => {
     state.pending.clear();
   });
 
-  // The added lines are read before the mutation lands, because after a write
-  // the previous content is gone. The body is read after, from disk.
   pi.on('tool_call', (event, ctx) => {
     const mutation = extractMutation(event, ctx.cwd);
     if (mutation === undefined || !isReviewablePath(mutation.relativePath)) {
@@ -171,9 +173,13 @@ export function registerJevGuard(
     return undefined;
   });
 
-  pi.on('tool_result', async (event, ctx) => {
+  pi.on('tool_result', (event, ctx) => {
     const pending = state.pending.get(event.toolCallId);
     state.pending.delete(event.toolCallId);
+    if (!event.isError && pending !== undefined) {
+      state.queue.invalidate(pending.relativePath);
+      state.queue.invalidate('sideroom_todo');
+    }
     const apiKey = dependencies.apiKey();
     if (
       apiKey === undefined ||
@@ -196,6 +202,7 @@ export function registerJevGuard(
         const check = detectCheckCommand(ctx.cwd);
         if (check !== undefined && commandMatches(event.input.command, check)) {
           state.evidence.checks = 'failed';
+          state.queue.invalidate('sideroom_todo');
         }
       }
       return undefined;
@@ -204,11 +211,13 @@ export function registerJevGuard(
       const check = detectCheckCommand(ctx.cwd);
       if (check !== undefined && commandMatches(event.input.command, check)) {
         state.evidence.checks = 'passed';
+        state.queue.invalidate('sideroom_todo');
       }
       return undefined;
     }
     let requestBody: JevRequestBody | undefined;
     let subject: string;
+    let sourcePaths: readonly string[] = [];
     if (event.toolName === 'sideroom_ask') {
       if (
         typeof event.details !== 'object' ||
@@ -231,6 +240,7 @@ export function registerJevGuard(
         changedIds: completionIds(event.input),
       });
       subject = 'sideroom_todo';
+      sourcePaths = [...state.evidence.files.keys()];
     } else {
       if (
         pending === undefined ||
@@ -240,7 +250,7 @@ export function registerJevGuard(
       }
       subject = pending.relativePath;
       state.evidence.checks = 'stale';
-      // Replace cached evidence even when this version no longer fits the budget.
+      const previous = state.evidence.files.get(subject);
       state.evidence.files.delete(subject);
       if (!isWorthAsking(pending)) {
         state.evidence.partial = true;
@@ -256,7 +266,7 @@ export function registerJevGuard(
         subject,
         body,
         pending.kind,
-        pending.lines,
+        mergeReviewLines({ previous: previous?.change.addedLines ?? [], added: pending.lines, body }),
       );
       if (fileState === undefined) {
         state.evidence.partial = true;
@@ -264,46 +274,74 @@ export function registerJevGuard(
       }
       recordFileEvidence(state.evidence, fileState);
       requestBody = buildRequestBody(fileState);
+      sourcePaths = [subject, ...fileState.context.files.map((file) => file.path)];
     }
     if (requestBody === undefined) {
       return undefined;
     }
 
-    state.calls += 1;
-    const attempt = await askJevRequest({
-      transport: dependencies.transport,
-      apiKey,
-      requestBody,
+    const body = requestBody;
+    return state.queue.enqueue({
+      key: subject,
+      dependencies: sourcePaths,
       signal: ctx.signal,
-    });
-    if (attempt.failure !== undefined) {
-      registerFailure(state, attempt.failure);
-      dependencies.report(guardStatus(state), ctx);
-      return undefined;
-    }
+      run: async (signal) => {
+        if (!shouldCallJev(state) || dependencies.apiKey() !== apiKey || signal.aborted) {
+          return;
+        }
+        state.calls += 1;
+        const attempt = await askJevRequest({
+          transport: dependencies.transport,
+          apiKey,
+          requestBody: body,
+          signal,
+        });
+        if (signal.aborted || dependencies.apiKey() !== apiKey) {
+          return;
+        }
+        if (attempt.failure !== undefined) {
+          registerFailure(state, attempt.failure);
+          dependencies.report(guardStatus(state), ctx);
+          return undefined;
+        }
 
-    registerSuccess(state);
-    if (attempt.model !== undefined) {
-      state.lastModel = attempt.model;
-    }
-    dependencies.report(JEV_STATUS.ready, ctx);
+        registerSuccess(state);
+        if (attempt.model !== undefined) {
+          state.lastModel = attempt.model;
+        }
+        dependencies.report(JEV_STATUS.ready, ctx);
 
-    const findings = attempt.findings ?? [];
-    const fresh = findings.filter((finding) =>
-      isUnnoted(state, subject, finding),
-    );
-    if (fresh.length === 0) {
-      return undefined;
-    }
-    markNoted(state, subject, fresh);
-    const note: ReviewNote = {
-      text: formatFindings(subject, fresh),
-    };
-    pi.events.emit(REVIEW_NOTE_EVENT, note);
-    return undefined;
+        const findings = attempt.findings ?? [];
+        const fresh = findings.filter((finding) =>
+          isUnnoted(state, subject, finding),
+        );
+        if (fresh.length === 0) {
+          return undefined;
+        }
+        markNoted(state, subject, fresh);
+        const note: ReviewNote = {
+          text: formatFindings(subject, fresh),
+        };
+        pi.events.emit(REVIEW_NOTE_EVENT, note);
+        return undefined;
+      },
+    });
   });
 }
 
+interface ReviewLinesInput {
+  readonly previous: readonly string[];
+  readonly added: readonly AddedLine[];
+  readonly body: string;
+}
+
+function mergeReviewLines({ previous, added, body }: ReviewLinesInput): readonly AddedLine[] {
+  const changed = new Set([...previous, ...added.map((line) => line.text)].map((text) => text.trim()));
+  return body.split('\n').flatMap((text, index) =>
+    changed.has(text.trim()) ? [{ line: index + 1, text }] : [],
+  );
+}
+
 function isUnnoted(
   state: JevGuardState,
   path: string,
@@ -322,8 +360,6 @@ function markNoted(
   }
 }
 
-// A user abort says nothing about the service, and a rate limit clears on its
-// own, so neither may count toward switching Jev off.
 function registerFailure(state: JevGuardState, failure: JevFailure): void {
   if (failure === JEV_FAILURE.cancelled) {
     return;
@@ -351,8 +387,6 @@ function registerSuccess(state: JevGuardState): void {
   state.transientFailures = 0;
 }
 
-// A deletion-only edit leaves nothing for the questions to read, and only
-// the project-relative path of a supported language may leave the machine.
 function isWorthAsking(mutation: PendingMutation): boolean {
   return mutation.lines.length > 0 && isReviewablePath(mutation.relativePath);
 }

package/extensions/jev/index.ts

@@ -26,13 +26,10 @@ import {
   statusLabel,
 } from './ui.ts';
 
-// Pi loads extensions/*/index.ts through export default.
 export default function registerJev(pi: ExtensionAPI): void {
   const configPath = configPathFor(getAgentDir());
   const guardState = createJevGuardState();
 
-  // The key is read on each use instead of cached at load time, so a key stored
-  // during a running session takes effect without a restart.
   const readKey = () => resolveApiKey(process.env, configPath);
 
   const currentStatus = (): JevStatus => {

package/extensions/jev/key.ts

@@ -17,9 +17,6 @@ export function configPathFor(agentDirectory: string): string {
   return join(agentDirectory, SIDEROOM_CONFIG_FILE);
 }
 
-// The environment wins so containers and CI work with no file at all. A missing
-// or malformed config means "no key"; anything else about the file is a real
-// problem and surfaces instead of hiding.
 export function resolveApiKey(
   environment: Readonly<Record<string, string | undefined>>,
   configPath: string,

package/extensions/jev/model.ts

@@ -6,14 +6,8 @@ export type { AddedLine } from '../rules/model.ts';
 export const JEV_ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
 export const JEV_MODEL = 'jev-latest';
 
-// A noul answer carries a probability and no confidence, so this cutoff is the
-// only brake. Below it Jev is saying it has nothing to go on, which would be
-// noise on every edit.
 export const VIOLATION_PROBABILITY = 0.8;
 
-// TypeSafe documents 32k tokens for state plus the longest question and 64k
-// for the full request. JSON UTF-8 bytes are a deliberately conservative
-// upper bound; no third-party tokenizer can promise the model's exact count.
 export const MAX_STATE_BYTES = 32_000;
 export const MAX_REQUEST_BYTES = 64_000;
 
@@ -30,7 +24,6 @@ export interface JevRule {
   readonly question: JevNoulQuestion;
 }
 
-// Questions must only use evidence in the file and the selected direct neighbours.
 export const JEV_RULES: readonly JevRule[] = [
   {
     id: 'guard-clauses',
@@ -290,7 +283,6 @@ export function addedLinesForEdit(
   return edits.flatMap((edit) => addedLines(edit.oldText, edit.newText));
 }
 
-// Questions are about code structure; a README or a lockfile has no useful state.
 export function isReviewablePath(path: string): boolean {
   return languageForPath(path) !== LANGUAGE.generic;
 }

package/extensions/jev/queue.ts

@@ -0,0 +1,125 @@
+const MAX_QUEUED_REVIEWS = 16;
+
+interface ReviewJob {
+  readonly key: string;
+  readonly dependencies?: readonly string[];
+  readonly signal?: AbortSignal;
+  readonly run: (signal: AbortSignal) => Promise<void>;
+}
+
+interface QueuedReview extends ReviewJob {
+  readonly controller: AbortController;
+  readonly signal: AbortSignal;
+}
+
+export class JevReviewQueue {
+  private readonly queued = new Map<string, QueuedReview>();
+  private active: QueuedReview | undefined;
+  private running: Promise<void> | undefined;
+  private failures: unknown[] = [];
+  private readonly waiting = new Set<QueuedReview>();
+
+  enqueue(job: ReviewJob): Promise<void> | undefined {
+    this.invalidate(job.key);
+    const controller = new AbortController();
+    const signal = job.signal === undefined
+      ? controller.signal
+      : AbortSignal.any([controller.signal, job.signal]);
+    const review = { ...job, controller, signal };
+    if (this.queued.size >= MAX_QUEUED_REVIEWS) {
+      this.waiting.add(review);
+      return this.enqueueWhenReady(review);
+    }
+    this.queued.set(job.key, review);
+    this.pump();
+    return undefined;
+  }
+
+  private async enqueueWhenReady(job: QueuedReview): Promise<void> {
+    try {
+      while (this.queued.size >= MAX_QUEUED_REVIEWS && this.running !== undefined && !job.signal.aborted) {
+        await this.running;
+      }
+      if (!job.signal.aborted) {
+        this.queued.set(job.key, job);
+        this.pump();
+      }
+    } finally {
+      this.waiting.delete(job);
+    }
+  }
+
+  invalidate(path: string): void {
+    for (const [key, job] of this.queued) {
+      if (key === path || job.dependencies?.includes(path)) {
+        job.controller.abort();
+        this.queued.delete(key);
+      }
+    }
+    for (const job of this.waiting) {
+      if (job.key === path || job.dependencies?.includes(path)) {
+        job.controller.abort();
+      }
+    }
+    if (this.active?.key === path || this.active?.dependencies?.includes(path)) {
+      this.active.controller.abort();
+    }
+  }
+
+  cancel(): void {
+    this.active?.controller.abort();
+    for (const job of this.queued.values()) {
+      job.controller.abort();
+    }
+    this.queued.clear();
+    for (const job of this.waiting) {
+      job.controller.abort();
+    }
+    this.waiting.clear();
+    this.failures = [];
+  }
+
+  async drain(): Promise<void> {
+    while (this.running !== undefined || this.waiting.size > 0) {
+      await this.running;
+    }
+    if (this.failures.length > 0) {
+      const failures = this.failures;
+      this.failures = [];
+      throw new AggregateError(failures, 'Jev background review failed');
+    }
+  }
+
+  private pump(): void {
+    if (this.running !== undefined) {
+      return;
+    }
+    const next = this.queued.entries().next().value;
+    if (next === undefined) {
+      return;
+    }
+    const [key, job] = next;
+    this.queued.delete(key);
+    if (job.signal.aborted) {
+      this.pump();
+      return;
+    }
+    this.active = job;
+    this.running = Promise.resolve()
+      .then(() => {
+        if (!job.signal.aborted) {
+          return job.run(job.signal);
+        }
+      })
+      .catch((error: unknown) => {
+        if (!job.signal.aborted) {
+          this.failures.push(error);
+        }
+      })
+      .finally(() => {
+        this.active = undefined;
+        this.running = undefined;
+        this.pump();
+      });
+  }
+}

package/extensions/jev/ui.ts

@@ -15,14 +15,9 @@ export const JEV_SHORTCUT = 'f10';
 const MASK_CHARACTER = '•';
 const CLEAR_KEY = Key.ctrl('u');
 
-// Pi wraps every paste in bracketed-paste markers before it reaches a component,
-// so the leading escape byte made the whole chunk look like a control sequence
-// and nothing landed in the field.
 const PASTE_START = '\x1b[200~';
 const PASTE_END = '\x1b[201~';
 
-// A pasted line usually carries a trailing newline, and no key holds
-// whitespace, so everything unprintable is dropped.
 export const MAX_KEY_LENGTH = 512;
 
 const STATUS_LABEL: Readonly<Record<JevStatus, string>> = {
@@ -102,8 +97,6 @@ export function createJevKeyController(
   };
 }
 
-// The packaged Input component has no masking, and a key must never render, so
-// this draws its own single masked field.
 export class JevKeyOverlay implements Component {
   private entry = '';
   private readonly tui: TUI;
@@ -236,9 +229,6 @@ export class JevKeyOverlay implements Component {
   }
 }
 
-// Pi re-wraps paste content as `ESC[200~ ... ESC[201~`, so the payload is read
-// between the markers. A paste split across chunks still contributes whatever
-// arrived after the opening marker.
 export function readPastedKey(keyData: string): string | undefined {
   const start = keyData.indexOf(PASTE_START);
   if (start === -1) {
@@ -250,14 +240,10 @@ export function readPastedKey(keyData: string): string | undefined {
   return printableOnly(body);
 }
 
-// C0 control bytes and DEL are the only boundaries that matter here, and they
-// live in one place so the two input paths cannot drift apart.
 function isControlCode(code: number): boolean {
   return code < 0x20 || code === 0x7f;
 }
 
-// Paste drops the space as well: no key holds one, and a pasted line carries a
-// trailing newline that would otherwise sit right before the closing marker.
 function printableOnly(text: string): string {
   let printable = '';
   for (const character of text) {

package/extensions/modified-files/index.ts

@@ -13,7 +13,6 @@ 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(

package/extensions/monorepo-skills/index.ts

@@ -3,7 +3,6 @@ import { areSkillsDisabled } from './flags.ts';
 import { appendMonorepoSkillsNote } from './prompt.ts';
 import { findMonorepoSkillPaths } from './scan.ts';
 
-// Pi loads extensions/*/index.ts through export default.
 export default function registerMonorepoSkills(pi: ExtensionAPI): void {
   let hasMonorepoSkills = false;
 

package/extensions/persona/checks.ts

@@ -11,8 +11,6 @@ interface ProhibitionDetector {
   readonly pattern: RegExp;
 }
 
-// Each detector is a heuristic for one prohibition. The rule text in the
-// catalog stays authoritative; a detector never fires on its own judgement.
 const DETECTORS: readonly ProhibitionDetector[] = [
   {
     prohibitionId: 'decorative-symbols',
@@ -108,8 +106,6 @@ function countLines(content: string | undefined): Map<string, number> {
   return counts;
 }
 
-// Detector matches are short by construction; drop the bullet or indentation
-// they carry so the reason stays on one line.
 function excerptOf(match: string): string {
   const singleLine = match.replaceAll(/\s+/gu, ' ').trim();
   return singleLine.replace(/^[>*+-]+\s*/u, '');

package/extensions/persona/guard.ts

@@ -6,6 +6,12 @@ import {
 } from '@earendil-works/pi-coding-agent';
 import { resolveFileToolPath } from '../shared/file-path.ts';
 import { readFileIfExists } from '../shared/read-file.ts';
+import {
+  registerSettleGuard,
+  registerSettleSupplement,
+  SETTLE_PRIORITY,
+  withHiddenSteer,
+} from '../shared/settle.ts';
 import {
   PERSONA_STEER_TYPE,
   type ProhibitionId,
@@ -23,11 +29,9 @@ import {
   formatSteer,
 } from './model.ts';
 
-// A rule that keeps firing degrades to a steer instead of trapping the agent.
 const BLOCK_DEGRADE_AFTER = 3;
 const CLEAN_RESET_AFTER = 5;
 
-// One agent run can be corrected at most this many times.
 const STEER_LIMIT_PER_RUN = 3;
 
 interface ExtractedMutation {
@@ -40,6 +44,7 @@ export interface PersonaGuardState {
   cleanMutations: number;
   steersThisRun: number;
   blocksThisRun: number;
+  pendingProse: string | undefined;
 }
 
 export function createPersonaGuardState(): PersonaGuardState {
@@ -48,12 +53,14 @@ export function createPersonaGuardState(): PersonaGuardState {
     cleanMutations: 0,
     steersThisRun: 0,
     blocksThisRun: 0,
+    pendingProse: undefined,
   };
 }
 
 export function resetPersonaRun(state: PersonaGuardState): void {
   state.steersThisRun = 0;
   state.blocksThisRun = 0;
+  state.pendingProse = undefined;
 }
 
 export function registerPersonaGuard(
@@ -73,10 +80,14 @@ export function registerPersonaGuard(
     return blockDecision;
   });
 
-  pi.on('message_end', (event, ctx) => {
+  pi.on('message_end', (event) => {
     if (event.message.role !== 'assistant') {
       return undefined;
     }
+    state.pendingProse = undefined;
+    if (event.message.stopReason !== 'stop') {
+      return undefined;
+    }
     const violations = findViolations(
       assistantMessageText(event.message.content),
       TEXT_SCOPE.prose,
@@ -85,10 +96,38 @@ export function registerPersonaGuard(
       return undefined;
     }
 
-    sendPersonaSteer(pi, state, formatSteer(violations));
-    report(ctx);
+    state.pendingProse = formatSteer(violations);
     return undefined;
   });
+
+  const pending = () =>
+    state.pendingProse !== undefined &&
+    state.steersThisRun < STEER_LIMIT_PER_RUN;
+  const prepare = (ctx: ExtensionContext) => {
+    if (
+      state.pendingProse === undefined ||
+      state.steersThisRun >= STEER_LIMIT_PER_RUN
+    ) {
+      return undefined;
+    }
+    const content = state.pendingProse;
+    state.pendingProse = undefined;
+    state.steersThisRun += 1;
+    report(ctx);
+    return { customType: PERSONA_STEER_TYPE, content };
+  };
+  registerSettleSupplement(pi, prepare);
+  registerSettleGuard(pi, {
+    priority: SETTLE_PRIORITY.persona,
+    pending,
+    handle: (event, ctx) => {
+      const message = prepare(ctx);
+      if (message === undefined) {
+        return;
+      }
+      return withHiddenSteer({ event, ...message });
+    },
+  });
 }
 
 function applyArtifactOutcome(
@@ -160,7 +199,7 @@ function sendPersonaSteer(
   state.steersThisRun += 1;
   pi.sendMessage(
     { customType: PERSONA_STEER_TYPE, content, display: false },
-    { triggerTurn: true, deliverAs: 'steer' },
+    { triggerTurn: false, deliverAs: 'steer' },
   );
 }
 

package/extensions/persona/index.ts

@@ -20,7 +20,6 @@ export const PERSONA_DESCRIPTION =
 export const PERSONA_PROMPT_SNIPPET =
   'Load the complete writing guide before substantial user-facing prose.';
 
-// Pi loads extensions/*/index.ts through export default.
 export default function registerPersona(pi: ExtensionAPI): void {
   const state = createPersonaGuardState();
   const publishStatus = (ctx: ExtensionContext): void => {
@@ -34,7 +33,10 @@ export default function registerPersona(pi: ExtensionAPI): void {
   };
   registerPersonaGuard(pi, state, publishStatus);
 
-  pi.on('session_start', (_event, ctx) => publishStatus(ctx));
+  pi.on('session_start', (_event, ctx) => {
+    resetPersonaRun(state);
+    publishStatus(ctx);
+  });
 
   pi.on('before_agent_start', (event, ctx) => {
     resetPersonaRun(state);

package/extensions/persona/model.ts

@@ -1,8 +1,6 @@
 import { PERSONA_TOOL_NAME, PROHIBITIONS, VOICE_RULES } from './catalog.ts';
 import type { ProhibitionViolation } from './checks.ts';
 
-// Pi narrows these blocks before handing the message over; the shape is
-// structural so no runtime decoding is needed here.
 export interface TextBlock {
   readonly type: string;
   readonly text?: string;

package/extensions/persona/prompt.ts

@@ -15,8 +15,6 @@ const PROHIBITION_SUMMARY = PROHIBITIONS.map(
 const ENFORCEMENT_SUMMARY =
   'A write/edit adding a decorative symbol is blocked; other violations trigger a steer.';
 
-// Static Do/Don't pairs. Literals only: no per-turn data, so the reminder
-// stays byte-identical across turns and the provider prompt cache holds.
 export const PERSONA_EXAMPLES = [
   "Do: Your work list stays with this conversation, not in project files. Don't: Session-scoped board state persists outside the repository.",
   "Do: To get a fresh answer, turn off the cache (stored results). Don't: Disable the cache invalidation pipeline.",