@rmrdeveloper/sideroom-pi 8.8.0 → 8.10.0

package/README.md

@@ -51,10 +51,11 @@ Sideroom answers each one with a small, opinionated surface:
 | Silent guessing | `sideroom_ask` — questions with an opinion, one batch at a time |
 | Invisible work | `sideroom_todo` — a live board above the editor, always one step in focus |
 | Repo pollution | Session-branch state — the board and history die with the session, never with a commit |
-| Style drift | A pre-edit gate + the on-demand `sideroom-guidelines` skill |
+| Style drift | A pre-edit gate + the on-demand `sideroom-guidelines` skill + an end-of-turn review steer |
 | Invisible monorepo skills | `monorepo-skills` — trusted child folders join Pi's available skill list |
 | Vague plans | `sideroom-grill` — an interview that settles the words before the work |
 | Unapplied guidelines | `sideroom_rules` — mechanical checks that block or flag the lines you add |
+| Unchecked judgment rules | `jev` — asks a decision model about the six rules no check can decide |
 | Unclear answers | `sideroom_persona` — one voice: direct, plain, and free of jargon it invented |
 | Premature completion | `sideroom_done` — steers back to the project's check command before finishing |
 | Work left unexplained | `explain` — offers a walkthrough and how to test it once the work settles |
@@ -157,7 +158,10 @@ full read of the packaged skill and, for supported targets, the one complete
 language guide under `skills/sideroom-guidelines/references/languages/`.
 Each guide mirrors all 19 rules in the canonical seed with idiomatic examples.
 The seed, `assets/artifacts/GUIDELINES_TEMPLATE.md`, is never pasted into the
-system prompt.
+system prompt. After any successful mutation, one hidden review steer fires when
+the turn settles and asks the agent to re-check every changed file against the
+loaded guide and run the relevant formatter, linter, type checks, and tests —
+so the contract is applied, not just read.
 
 ### Monorepo skills — child skills are still project skills
 
@@ -183,6 +187,28 @@ appended as notes to the tool result. A per-rule circuit breaker degrades a
 repeatedly firing block to a note so the agent never dead-locks. No files
 written, no config read: the catalog ships with the package.
 
+### Jev — judgment where no check reaches
+
+Reading the guide covers the mechanical rules. `jev` covers the other kind: one
+optional call to TypeSafe's Jev decision model about the six guide rules a
+single file can answer (guard clauses, fail fast, command/query separation,
+null handling, immutability, validate once) on the file a `write` or `edit` just
+changed. The answer arrives as a probability, and when it clears the cutoff the
+note travels with the guidelines review at the end of the run instead of
+interrupting each edit. READMEs, JSON, lockfiles, deletion-only edits, and files
+outside the project are never sent.
+
+It never blocks and never enters the system prompt. The state is the file and
+the added lines and nothing else — no conversation, no session, no neighbours.
+The footer counts the calls the session made, and `F10` shows the same count
+beside the key source. Without a key nothing is called, and when Jev runs out of
+quota, rejects the key,
+or stops answering, the extension goes quiet without touching the turn. A rate
+limit only pauses it until your next prompt, and Escape cuts a request in
+flight. The key
+lives in `TYPESAFE_API_KEY` or in your agent directory, and `F10` captures it
+without ever writing it to the session.
+
 ### Persona — one voice, not a costume
 
 `sideroom_persona` is the agent's voice, and there is exactly one of it. A
@@ -208,11 +234,14 @@ nothing is detectable, the gate does nothing.
 
 When an implementation settles, `explain` steers the agent to offer a
 walkthrough through `sideroom_ask`: explain the changes only, how to test them
-only, both, or nothing. It fires on `agent_settled`, the point where
-no retry, compaction, or queued message is left, so the offer never lands on
-work that is about to be redone. Once per turn, only when the turn touched at
-least five distinct files, and only in the TUI, because `sideroom_ask` cannot
-run anywhere else. No tool, no widget, no persisted state.
+only, both, or nothing. It fires on `agent_before_settle`, after every retry
+and compaction recovery, so the offer never lands on work that is about to be
+redone, and it stays inside the same run. It waits one boundary so the
+guidelines review runs first; both use the same event, and Pi would otherwise
+order them by extension load. It stays quiet after Escape, after an error, and
+while a message you typed is waiting. Once per turn, only when the turn touched at least five distinct
+files, and only in the TUI, because `sideroom_ask` cannot run anywhere else. No
+tool, no widget, no persisted state.
 
 ## Quick path
 
@@ -287,8 +316,14 @@ also fully read the packaged guide matching the target path. Reads with
 `offset` or `limit`, failed reads, and same-named files elsewhere do not count.
 The extension blocks the mutation until the required reads succeed; unsupported
 languages use the shared table. Do not route around
-the gate through Bash or another file-mutation path. Before finishing, review
-the diff against the loaded guide and run the relevant project checks.
+the gate through Bash or another file-mutation path. After any successful
+`write`/`edit`, one hidden review steer fires on `agent_before_settle` (at most
+once per turn) asking the agent to re-check every changed file against the
+loaded guide and run the relevant project checks. It is skipped after Escape,
+after an error, and while a user message is pending. Interactive input sent
+while the agent is idle clears the steer flags; a message typed during a run
+and `before_agent_start` do not, so a steer continuation never re-triggers
+itself.
 
 ### Monorepo-skills contract
 
@@ -315,11 +350,36 @@ the diff against the loaded guide and run the relevant project checks.
 - A rule that blocks three times in a run degrades to a warning until five
   clean checks or a new interactive prompt reset it.
 
+### Jev contract
+
+- Off without a key: no request, and behavior identical to a package without
+  this extension.
+- Warn only. A finding goes to the guidelines review on `sideroom:review-note`
+  and rides its end-of-run steer, with one follow-up per turn for notes that
+  arrive after the review fired; nothing blocks and nothing reaches the system
+  prompt.
+- One request per successful `write`/`edit` of a project file in a supported
+  language that added lines, with six `noul` questions on one shared state of
+  the project-relative path, the file body, and the added lines.
+- A serialized state over 60k characters is skipped rather than truncated. An
+  answer at or above `0.8` probability becomes a note.
+- The request follows the run's abort signal; a cancelled request is not a
+  failure.
+- Quota (`402`) and a rejected key (`401`, `403`) stop the calls immediately. A
+  rate limit (`429`) pauses them until the next idle prompt. Network errors and
+  other `4xx`/`5xx` stop after three consecutive failures. A success rearms the
+  breaker, and `F10` rearms it by hand.
+- Every request increments a session call counter, shown in the footer and on
+  `F10`; it resets on `session_start` and is never persisted.
+- The key comes from `TYPESAFE_API_KEY` or from
+  `getAgentDir()/sideroom.json` at mode `0600`, and never enters the session.
+
 ### Persona contract
 
 - One built-in voice. No profiles, no switching, and no persisted profile
-  state; runtime guard counters stay in memory. The footer status is derived
-  from the catalog.
+  state; runtime guard counters stay in memory. The footer shows the run's block
+  and steer counts (`persona: direct · 2 blocks · 1 steer`) and drops back to
+  `persona: direct` on the next run.
 - Injection: a short reminder appended in `before_agent_start`, chained after
   the other extensions and idempotent by heading, so it returns after
   compaction.
@@ -343,9 +403,13 @@ the diff against the loaded guide and run the relevant project checks.
 
 ### Explain contract
 
-- Trigger: `agent_settled` with at least five distinct files mutated since the
-  last user prompt, in TUI mode. File identity follows Pi's path aliases and
-  canonicalizes existing paths.
+- Trigger: `agent_before_settle` with at least five distinct files mutated
+  since the last idle user prompt, in TUI mode, on a completed run with no user
+  message pending. File identity follows Pi's path aliases and canonicalizes
+  existing paths.
+- One boundary of delay: the guidelines review steers on the same event, and Pi
+  runs both handlers in extension load order, so `explain` offers at the next
+  boundary.
 - The steer names the intent; the agent writes the question in the user's
   language with four options, one of them a decline, and one recommendation.
   `sideroom_ask` still adds *Out of scope* and the custom answer.

package/extensions/explain/guard.ts

@@ -4,12 +4,20 @@ import {
   isWriteToolResult,
 } from '@earendil-works/pi-coding-agent';
 import {
+  acceptsSettleSteer,
+  startsUserTurn,
+  withHiddenSteer,
+} from '../shared/settle.ts';
+import {
+  applyOfferDecision,
+  decideOffer,
+  EXPLAIN_DECISION,
   EXPLAIN_OFFER,
   EXPLAIN_OFFER_TYPE,
   type ExplainState,
   mutationPathKey,
+  recordMutation,
   resetExplainTurn,
-  shouldOfferExplanation,
 } from './model.ts';
 
 interface FileToolInput {
@@ -21,7 +29,7 @@ export function registerExplainGuard(
   state: ExplainState,
 ): void {
   pi.on('input', (event) => {
-    if (event.source !== 'interactive' && event.source !== 'rpc') {
+    if (!startsUserTurn(event)) {
       return;
     }
     resetExplainTurn(state);
@@ -40,23 +48,21 @@ export function registerExplainGuard(
     if (pathKey === undefined) {
       return;
     }
-    state.mutatedFilesThisTurn.add(pathKey);
+    recordMutation(state, pathKey);
   });
 
-  // agent_settled is the only point with no retry, compaction, or queued
-  // continuation left, so the walkthrough is never offered over reworked work.
-  pi.on('agent_settled', (_event, ctx) => {
-    if (!shouldOfferExplanation(state, ctx.mode)) {
+  // agent_before_settle runs after retries and compaction recovery, so the
+  // walkthrough is never offered over reworked work, and its continuation
+  // stays inside the same run instead of starting a second one.
+  pi.on('agent_before_settle', (event, ctx) => {
+    if (!acceptsSettleSteer(event)) {
+      return;
+    }
+    const decision = decideOffer(state, ctx.mode);
+    applyOfferDecision(state, decision);
+    if (decision !== EXPLAIN_DECISION.send) {
       return;
     }
-    state.offeredThisTurn = true;
-    pi.sendMessage(
-      {
-        customType: EXPLAIN_OFFER_TYPE,
-        content: EXPLAIN_OFFER,
-        display: false,
-      },
-      { triggerTurn: true, deliverAs: 'steer' },
-    );
+    return withHiddenSteer(event, EXPLAIN_OFFER_TYPE, EXPLAIN_OFFER);
   });
 }

package/extensions/explain/model.ts

@@ -11,17 +11,35 @@ const TUI_MODE = 'tui';
 export const EXPLAIN_OFFER =
   "Use sideroom_ask for one question in the user's language with four parallel options: changes only, test steps only, both, or no explanation. Recommend changes only.";
 
+export const EXPLAIN_DECISION = {
+  send: 'send',
+  defer: 'defer',
+  none: 'none',
+} as const;
+
+export type ExplainDecision =
+  (typeof EXPLAIN_DECISION)[keyof typeof EXPLAIN_DECISION];
+
 export interface ExplainState {
   mutatedFilesThisTurn: Set<string>;
+  mutatedSinceSettle: boolean;
+  pendingOffer: boolean;
   offeredThisTurn: boolean;
 }
 
 export function createExplainState(): ExplainState {
-  return { mutatedFilesThisTurn: new Set(), offeredThisTurn: false };
+  return {
+    mutatedFilesThisTurn: new Set(),
+    mutatedSinceSettle: false,
+    pendingOffer: false,
+    offeredThisTurn: false,
+  };
 }
 
 export function resetExplainTurn(state: ExplainState): void {
   state.mutatedFilesThisTurn.clear();
+  state.mutatedSinceSettle = false;
+  state.pendingOffer = false;
   state.offeredThisTurn = false;
 }
 
@@ -31,14 +49,46 @@ export function mutationPathKey(cwd: string, path: string): string | undefined {
   return resolveFileToolPath(cwd, path);
 }
 
-// sideroom_ask rejects every mode but the TUI, so the offer is gated the same way.
-export function shouldOfferExplanation(
+export function recordMutation(state: ExplainState, pathKey: string): void {
+  state.mutatedFilesThisTurn.add(pathKey);
+  state.mutatedSinceSettle = true;
+}
+
+// The guidelines review steers at the first settle boundary after a mutation,
+// and both handlers run in an extension load order Sideroom does not control.
+// Explain holds its steer back one boundary so the review always runs first;
+// the review's continuation is what brings the next boundary.
+export function decideOffer(
   state: ExplainState,
   mode: string,
-): boolean {
-  return (
+): ExplainDecision {
+  const thresholdReached =
     mode === TUI_MODE &&
-    state.mutatedFilesThisTurn.size >= EXPLAIN_FILE_THRESHOLD &&
-    !state.offeredThisTurn
-  );
+    !state.offeredThisTurn &&
+    state.mutatedFilesThisTurn.size >= EXPLAIN_FILE_THRESHOLD;
+  if (state.pendingOffer && thresholdReached) {
+    return EXPLAIN_DECISION.send;
+  }
+  if (
+    thresholdReached ||
+    (mode === TUI_MODE && state.mutatedSinceSettle && !state.offeredThisTurn)
+  ) {
+    return EXPLAIN_DECISION.defer;
+  }
+  return EXPLAIN_DECISION.none;
+}
+
+export function applyOfferDecision(
+  state: ExplainState,
+  decision: ExplainDecision,
+): void {
+  if (decision === EXPLAIN_DECISION.send) {
+    state.offeredThisTurn = true;
+    state.pendingOffer = false;
+  } else if (decision === EXPLAIN_DECISION.defer) {
+    state.pendingOffer = true;
+  } else {
+    state.pendingOffer = false;
+  }
+  state.mutatedSinceSettle = false;
 }

package/extensions/guidelines/index.ts

@@ -5,12 +5,24 @@ import {
   resetGuidelineReadState,
 } from './guard.ts';
 import { appendGuidelinesReminder } from './prompt.ts';
+import {
+  createReviewState,
+  registerReviewGuard,
+  resetReviewTurn,
+} from './review.ts';
 
 // Pi loads extensions/*/index.ts through export default.
 export default function registerGuidelines(pi: ExtensionAPI): void {
   const readState = createGuidelineReadState();
   registerGuidelineGuard(pi, readState);
 
+  const reviewState = createReviewState();
+  registerReviewGuard(pi, reviewState);
+  pi.on('session_start', () => {
+    resetGuidelineReadState(readState);
+    resetReviewTurn(reviewState);
+  });
+
   pi.on('before_agent_start', (event) => {
     resetGuidelineReadState(readState);
     const systemPrompt = appendGuidelinesReminder(event.systemPrompt);

package/extensions/guidelines/prompt.ts

@@ -15,8 +15,7 @@ export const GUIDELINES_REMINDER = `${GUIDELINES_REMINDER_HEADING}
 Before the first write or edit in each agent run, use the read tool without offset or limit to load these files in full:
 - ${GUIDELINE_SKILL_PATH}
 - for the extension of the file you will change, one of: ${LANGUAGE_GUIDE_INDEX}
-A required read counts only when it succeeds without truncation. Until all required reads succeed, do not call write or edit and do not mutate files through bash or another tool; the extension blocks those mutations.
-After changing files, review the code against the loaded guide and run the relevant formatter, linter, type checks, and tests.`;
+A required read counts only when it succeeds without truncation. Until all required reads succeed, do not call write or edit and do not mutate files through bash or another tool; the extension blocks those mutations.`;
 
 export function appendGuidelinesReminder(systemPrompt: string): string {
   if (systemPrompt.includes(GUIDELINES_REMINDER_HEADING)) {

package/extensions/guidelines/review.ts

@@ -0,0 +1,115 @@
+import {
+  type ExtensionAPI,
+  isEditToolResult,
+  isWriteToolResult,
+} from '@earendil-works/pi-coding-agent';
+import { isReviewNote, REVIEW_NOTE_EVENT } from '../shared/review-note.ts';
+import {
+  acceptsSettleSteer,
+  startsUserTurn,
+  withHiddenSteer,
+} from '../shared/settle.ts';
+
+export const REVIEW_STEER_TYPE = 'sideroom-guidelines-review';
+
+export const REVIEW_STEER =
+  'Review every file this run changed against the loaded Sideroom language guide: fix any mechanical, structural, or architectural rule violations in those files, then run the relevant formatter, linter, type checks, and tests. If the guide is no longer in context, re-read it in full first.';
+
+export const REVIEW_NOTES_STEER =
+  'Files changed during the review drew the semantic notes below. Verify each against the loaded Sideroom language guide, fix only real violations, then rerun the relevant checks.';
+
+export interface ReviewState {
+  mutated: boolean;
+  steeredThisTurn: boolean;
+  notesSteeredThisTurn: boolean;
+  notes: string[];
+}
+
+export function createReviewState(): ReviewState {
+  return {
+    mutated: false,
+    steeredThisTurn: false,
+    notesSteeredThisTurn: false,
+    notes: [],
+  };
+}
+
+export function resetReviewTurn(state: ReviewState): void {
+  state.mutated = false;
+  state.steeredThisTurn = false;
+  state.notesSteeredThisTurn = false;
+  state.notes = [];
+}
+
+export function shouldReview(state: ReviewState): boolean {
+  return state.mutated && !state.steeredThisTurn;
+}
+
+// Notes that arrive after the review fired get one follow-up per turn, so a
+// fix that draws new notes cannot keep the run going.
+export function pendingReviewSteer(state: ReviewState): string | undefined {
+  if (shouldReview(state)) {
+    return withNotes(REVIEW_STEER, state.notes);
+  }
+  if (
+    state.steeredThisTurn &&
+    !state.notesSteeredThisTurn &&
+    state.notes.length > 0
+  ) {
+    return withNotes(REVIEW_NOTES_STEER, state.notes);
+  }
+  return undefined;
+}
+
+export function markReviewSteered(state: ReviewState): void {
+  if (state.steeredThisTurn) {
+    state.notesSteeredThisTurn = true;
+  }
+  state.steeredThisTurn = true;
+  state.notes = [];
+}
+
+function withNotes(lead: string, notes: readonly string[]): string {
+  return [lead, ...notes].join('\n\n');
+}
+
+export function registerReviewGuard(
+  pi: ExtensionAPI,
+  state: ReviewState,
+): void {
+  pi.on('input', (event) => {
+    if (!startsUserTurn(event)) {
+      return;
+    }
+    resetReviewTurn(state);
+  });
+
+  pi.on('tool_result', (event) => {
+    if (event.isError) {
+      return;
+    }
+    if (!isEditToolResult(event) && !isWriteToolResult(event)) {
+      return;
+    }
+    state.mutated = true;
+  });
+
+  pi.events.on(REVIEW_NOTE_EVENT, (payload) => {
+    if (isReviewNote(payload)) {
+      state.notes.push(payload.text);
+    }
+  });
+
+  // agent_before_settle runs after retries and compaction recovery, and its
+  // continuation stays inside the same run. agent_settled is notification-only:
+  // a steer sent there starts a second run after the user already saw the
+  // agent stop, and it fires even when the user pressed Escape.
+  pi.on('agent_before_settle', (event) => {
+    const steer = pendingReviewSteer(state);
+    if (steer === undefined || !acceptsSettleSteer(event)) {
+      return;
+    }
+    markReviewSteered(state);
+    return withHiddenSteer(event, REVIEW_STEER_TYPE, steer);
+  });
+}

package/extensions/jev/client.ts

@@ -0,0 +1,137 @@
+import {
+  buildRequestBody,
+  JEV_ENDPOINT,
+  type JevFileState,
+  type JevFinding,
+  parseEnvelope,
+  readFindings,
+} from './model.ts';
+
+export const JEV_REQUEST_TIMEOUT_MS = 3_000;
+
+export const JEV_FAILURE = {
+  quota: 'quota',
+  auth: 'auth',
+  rateLimited: 'rateLimited',
+  transient: 'transient',
+  cancelled: 'cancelled',
+} as const;
+
+const HTTP_STATUS = {
+  unauthorized: 401,
+  paymentRequired: 402,
+  forbidden: 403,
+  tooManyRequests: 429,
+  firstClientError: 400,
+} as const;
+
+export type JevFailure = (typeof JEV_FAILURE)[keyof typeof JEV_FAILURE];
+
+export interface JevHttpRequest {
+  readonly apiKey: string;
+  readonly body: string;
+  readonly signal: AbortSignal | undefined;
+}
+
+export interface JevHttpResponse {
+  readonly status: number;
+  readonly text: string;
+}
+
+export type JevTransport = (
+  request: JevHttpRequest,
+) => Promise<JevHttpResponse>;
+
+export interface JevAttempt {
+  readonly findings: readonly JevFinding[] | undefined;
+  readonly model: string | undefined;
+  readonly failure: JevFailure | undefined;
+}
+
+// The endpoint is a package constant, never a value from the environment or the
+// session, so the outbound URL cannot be steered by the repository being edited.
+export function createFetchTransport(
+  timeoutMs: number = JEV_REQUEST_TIMEOUT_MS,
+): JevTransport {
+  return async (request) => {
+    const response = await fetch(JEV_ENDPOINT, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${request.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: request.body,
+      signal: requestSignal(timeoutMs, request.signal),
+    });
+    return { status: response.status, text: await response.text() };
+  };
+}
+
+// Pi waits for every tool_result handler before the result reaches the model,
+// so the user's Escape has to cut the request, not only the timeout.
+function requestSignal(
+  timeoutMs: number,
+  runSignal: AbortSignal | undefined,
+): AbortSignal {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  if (runSignal === undefined) {
+    return timeout;
+  }
+  return AbortSignal.any([timeout, runSignal]);
+}
+
+export function classifyStatus(status: number): JevFailure | undefined {
+  if (status === HTTP_STATUS.unauthorized || status === HTTP_STATUS.forbidden) {
+    return JEV_FAILURE.auth;
+  }
+  if (status === HTTP_STATUS.paymentRequired) {
+    return JEV_FAILURE.quota;
+  }
+  if (status === HTTP_STATUS.tooManyRequests) {
+    return JEV_FAILURE.rateLimited;
+  }
+  if (status >= HTTP_STATUS.firstClientError) {
+    return JEV_FAILURE.transient;
+  }
+  return undefined;
+}
+
+// A Jev failure is a missing note, never an error: the mutation already
+// succeeded and the mechanical rules already ran. So this returns a value
+// instead of throwing, and the caller only decides whether to keep calling.
+export async function askJev(
+  transport: JevTransport,
+  apiKey: string,
+  file: JevFileState,
+  signal: AbortSignal | undefined,
+): Promise<JevAttempt> {
+  const body = JSON.stringify(buildRequestBody(file));
+  let response: JevHttpResponse;
+  try {
+    response = await transport({ apiKey, body, signal });
+  } catch {
+    return {
+      findings: undefined,
+      model: undefined,
+      failure:
+        signal?.aborted === true
+          ? JEV_FAILURE.cancelled
+          : JEV_FAILURE.transient,
+    };
+  }
+
+  const failure = classifyStatus(response.status);
+  if (failure !== undefined) {
+    return { findings: undefined, model: undefined, failure };
+  }
+
+  const envelope = parseEnvelope(response.text);
+  if (envelope === undefined) {
+    return { findings: [], model: undefined, failure: undefined };
+  }
+  return {
+    findings: readFindings(envelope),
+    model: envelope.model,
+    failure: undefined,
+  };
+}