@rmrdeveloper/sideroom-pi 8.8.0 → 8.9.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,24 @@ 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 a note is appended to the tool
+result when it clears the cutoff.
+
+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. 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
@@ -210,9 +232,11 @@ 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.
+work that is about to be redone. It waits one settle so the guidelines review
+runs first; both fire on `agent_settled`, and Pi would otherwise order them by
+extension load. 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 +311,12 @@ 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_settled` (at most once
+per turn) asking the agent to re-check every changed file against the loaded
+guide and run the relevant project checks. Interactive input clears the steer
+flags; `before_agent_start` does not, so a steer continuation never re-triggers
+itself.
 
 ### Monorepo-skills contract
 
@@ -315,11 +343,30 @@ 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 is text appended to the tool result; nothing blocks and
+  nothing reaches the system prompt.
+- One request per successful `write`/`edit`, with six `noul` questions on one
+  shared state of the file body and the added lines.
+- A body over 60k characters is skipped rather than truncated. An answer at or
+  above `0.8` probability becomes a note.
+- Quota (`402`) and a rejected key (`401`, `403`) stop the calls immediately;
+  network errors, `429` and `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.
@@ -346,6 +393,9 @@ the diff against the loaded guide and run the relevant project checks.
 - 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.
+- One settle of delay: the guidelines review steers on the same event, and Pi
+  runs both deferred steers in extension load order, so `explain` offers at the
+  next settle.
 - 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,15 @@ import {
   isWriteToolResult,
 } from '@earendil-works/pi-coding-agent';
 import {
+  applyOfferDecision,
+  decideOffer,
+  EXPLAIN_DECISION,
   EXPLAIN_OFFER,
   EXPLAIN_OFFER_TYPE,
   type ExplainState,
   mutationPathKey,
+  recordMutation,
   resetExplainTurn,
-  shouldOfferExplanation,
 } from './model.ts';
 
 interface FileToolInput {
@@ -40,16 +43,17 @@ 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)) {
+    const decision = decideOffer(state, ctx.mode);
+    applyOfferDecision(state, decision);
+    if (decision !== EXPLAIN_DECISION.send) {
       return;
     }
-    state.offeredThisTurn = true;
     pi.sendMessage(
       {
         customType: EXPLAIN_OFFER_TYPE,

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,45 @@ 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 after a mutation, and
+// agent_settled runs both deferred steers in extension load order. Explain
+// holds its own steer back one settle so the review always runs first.
+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,70 @@
+import {
+  type ExtensionAPI,
+  isEditToolResult,
+  isWriteToolResult,
+} from '@earendil-works/pi-coding-agent';
+
+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 interface ReviewState {
+  mutated: boolean;
+  steeredThisTurn: boolean;
+}
+
+export function createReviewState(): ReviewState {
+  return { mutated: false, steeredThisTurn: false };
+}
+
+export function resetReviewTurn(state: ReviewState): void {
+  state.mutated = false;
+  state.steeredThisTurn = false;
+}
+
+export function shouldReview(state: ReviewState): boolean {
+  return state.mutated && !state.steeredThisTurn;
+}
+
+export function registerReviewGuard(
+  pi: ExtensionAPI,
+  state: ReviewState,
+): void {
+  pi.on('input', (event) => {
+    if (event.source !== 'interactive' && event.source !== 'rpc') {
+      return;
+    }
+    resetReviewTurn(state);
+  });
+
+  pi.on('tool_result', (event) => {
+    if (event.isError) {
+      return;
+    }
+    if (!isEditToolResult(event) && !isWriteToolResult(event)) {
+      return;
+    }
+    state.mutated = true;
+  });
+
+  // agent_settled is the only point with no retry, compaction, or queued
+  // continuation left, so the review never lands on work a retry is about to
+  // redo. Mark the flag before sending so the continuation this steer starts
+  // cannot re-trigger it; sendMessage is intentionally not awaited, matching
+  // explain, so the settle handler returns immediately.
+  pi.on('agent_settled', () => {
+    if (!shouldReview(state)) {
+      return;
+    }
+    state.steeredThisTurn = true;
+    pi.sendMessage(
+      {
+        customType: REVIEW_STEER_TYPE,
+        content: REVIEW_STEER,
+        display: false,
+      },
+      { triggerTurn: true, deliverAs: 'steer' },
+    );
+  });
+}

package/extensions/jev/client.ts

@@ -0,0 +1,106 @@
+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',
+  transient: 'transient',
+} as const;
+
+export type JevFailure = (typeof JEV_FAILURE)[keyof typeof JEV_FAILURE];
+
+export interface JevHttpRequest {
+  readonly apiKey: string;
+  readonly body: string;
+}
+
+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: AbortSignal.timeout(timeoutMs),
+    });
+    return { status: response.status, text: await response.text() };
+  };
+}
+
+export function classifyStatus(status: number): JevFailure | undefined {
+  if (status === 401 || status === 403) {
+    return JEV_FAILURE.auth;
+  }
+  if (status === 402) {
+    return JEV_FAILURE.quota;
+  }
+  if (status >= 400) {
+    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,
+): Promise<JevAttempt> {
+  const body = JSON.stringify(buildRequestBody(file));
+  let response: JevHttpResponse;
+  try {
+    response = await transport({ apiKey, body });
+  } catch {
+    return {
+      findings: undefined,
+      model: undefined,
+      failure: 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,
+  };
+}