@rmrdeveloper/sideroom-pi 8.8.0 → 8.10.0

package/extensions/jev/model.ts

@@ -0,0 +1,266 @@
+import { LANGUAGE, languageForPath } from '../rules/catalog.ts';
+import { type AddedLine, addedLines } from '../rules/model.ts';
+
+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;
+
+// The serialized state must stay well under the two documented budgets (64k
+// tokens for the whole request, 32k for the state plus the longest question). A
+// new file travels twice, as the body and as its added lines. A state that does
+// not fit is skipped, never truncated: half a file reads as a distorted picture
+// and Jev answers it with the same confidence.
+export const MAX_STATE_CHARACTERS = 60_000;
+
+const NOUL_TYPE = 'noul';
+
+export interface JevNoulQuestion {
+  readonly type: typeof NOUL_TYPE;
+  readonly instructions: string;
+  readonly criteria: { readonly true: string; readonly false: string };
+}
+
+export interface JevRule {
+  readonly id: string;
+  readonly question: JevNoulQuestion;
+}
+
+// The six guide rules that a single file can answer and that no mechanical
+// check covers. Rules 11, 12, 15, 16, 17 and 18 need the module's neighbours.
+export const JEV_RULES: readonly JevRule[] = [
+  {
+    id: 'guard-clauses',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'In `change.addedLines`, is the control flow nested so the main path is buried, instead of validating and exiting early?',
+      criteria: {
+        true: 'Conditionals nest two or more levels deep, or the main path sits inside a condition that could have returned early',
+        false:
+          'Each condition is handled with an early return or a flat sequence',
+      },
+    },
+  },
+  {
+    id: 'fail-fast',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'In `change.addedLines`, is an invalid or impossible state papered over with a silent fallback instead of failing immediately?',
+      criteria: {
+        true: 'A default value or a silent coercion hides a broken dependency or a state that should never happen',
+        false:
+          'An impossible or invalid case throws with a clear message, or no such case appears',
+      },
+    },
+  },
+  {
+    id: 'command-query',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'In `change.addedLines`, does a function both change state and return a value, or does something that reads like a query have a side effect?',
+      criteria: {
+        true: 'A function that returns data also mutates state, or a getter mutates',
+        false: 'Functions either change state or return data, never both',
+      },
+    },
+  },
+  {
+    id: 'null-handling',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'In `change.addedLines`, is the same empty value reused to mean several different states, or are `null` and `undefined` mixed for one meaning?',
+      criteria: {
+        true: 'One empty value carries more than one business meaning, or null and undefined stand for the same thing in different places',
+        false:
+          'One convention is used and each distinct state has its own value',
+      },
+    },
+  },
+  {
+    id: 'immutability',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'In `change.addedLines`, is an object or array received as a parameter modified in place?',
+      criteria: {
+        true: 'A parameter is pushed, assigned or deleted into, or a transform writes to state outside itself',
+        false: 'New values are returned instead of changing the inputs',
+      },
+    },
+  },
+  {
+    id: 'validate-once',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'In `change.addedLines`, is the same required, type or range check repeated after a boundary already owns that input?',
+      criteria: {
+        true: 'A rule already validated at the boundary is checked again deeper in the code',
+        false: 'Validation happens once, at the boundary that owns the input',
+      },
+    },
+  },
+];
+
+export interface JevFileState {
+  readonly file: {
+    readonly path: string;
+    readonly language: string;
+    readonly body: string;
+  };
+  readonly change: {
+    readonly kind: string;
+    readonly addedLines: readonly string[];
+  };
+}
+
+export interface JevRequestBody {
+  readonly model: string;
+  readonly state: JevFileState;
+  readonly questions: Readonly<Record<string, JevNoulQuestion>>;
+}
+
+export interface JevNoulAnswer {
+  readonly noul: number;
+}
+
+export interface JevResponseEnvelope {
+  readonly model: string | undefined;
+  readonly answers: Readonly<Record<string, JevNoulAnswer>> | undefined;
+}
+
+export interface JevFinding {
+  readonly ruleId: string;
+  readonly probability: number;
+}
+
+export function buildFileState(
+  path: string,
+  body: string,
+  kind: string,
+  lines: readonly AddedLine[],
+): JevFileState {
+  return {
+    file: { path, language: languageForPath(path), body },
+    change: { kind, addedLines: lines.map((line) => line.text) },
+  };
+}
+
+export function addedLinesForWrite(
+  previous: string | undefined,
+  next: string,
+): AddedLine[] {
+  return addedLines(previous, next);
+}
+
+export function addedLinesForEdit(
+  edits: readonly { readonly oldText: string; readonly newText: string }[],
+): AddedLine[] {
+  return edits.flatMap((edit) => addedLines(edit.oldText, edit.newText));
+}
+
+// The six questions are about code structure; a README or a lockfile would
+// spend a call on answers that mean nothing.
+export function isReviewablePath(path: string): boolean {
+  return languageForPath(path) !== LANGUAGE.generic;
+}
+
+export function stateFitsBudget(state: JevFileState): boolean {
+  return JSON.stringify(state).length <= MAX_STATE_CHARACTERS;
+}
+
+export function buildRequestBody(file: JevFileState): JevRequestBody {
+  const questions: Record<string, JevNoulQuestion> = {};
+  for (const rule of JEV_RULES) {
+    questions[rule.id] = rule.question;
+  }
+  return { model: JEV_MODEL, state: file, questions };
+}
+
+export function parseEnvelope(text: string): JevResponseEnvelope | undefined {
+  const payload = parseJsonObject(text);
+  if (payload === undefined) {
+    return undefined;
+  }
+  const model = typeof payload.model === 'string' ? payload.model : undefined;
+  return { model, answers: readAnswers(payload.answers) };
+}
+
+export function readFindings(
+  envelope: JevResponseEnvelope,
+): readonly JevFinding[] {
+  const answers = envelope.answers;
+  if (answers === undefined) {
+    return [];
+  }
+  const findings: JevFinding[] = [];
+  for (const rule of JEV_RULES) {
+    const answer = answers[rule.id];
+    if (answer === undefined || answer.noul < VIOLATION_PROBABILITY) {
+      continue;
+    }
+    findings.push({ ruleId: rule.id, probability: answer.noul });
+  }
+  return findings;
+}
+
+export function findingKey(path: string, ruleId: string): string {
+  return `${path}#${ruleId}`;
+}
+
+export function formatFindings(
+  path: string,
+  findings: readonly JevFinding[],
+): string {
+  return [
+    `Sideroom Jev review flagged ${path}:`,
+    ...findings.map(
+      (finding) =>
+        `- [${finding.ruleId}] Jev scored ${finding.probability.toFixed(2)} probability that the added lines break this rule. Verify against the loaded guide before changing anything.`,
+    ),
+  ].join('\n');
+}
+
+function parseJsonObject(text: string): Record<string, unknown> | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      return undefined;
+    }
+    throw error;
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return undefined;
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function readAnswers(
+  value: unknown,
+): Record<string, JevNoulAnswer> | undefined {
+  if (typeof value !== 'object' || value === null) {
+    return undefined;
+  }
+  const answers: Record<string, JevNoulAnswer> = {};
+  for (const [id, entry] of Object.entries(value)) {
+    if (typeof entry !== 'object' || entry === null) {
+      continue;
+    }
+    const { noul } = entry as { noul?: unknown };
+    if (typeof noul === 'number') {
+      answers[id] = { noul };
+    }
+  }
+  return answers;
+}

package/extensions/jev/ui.ts

@@ -0,0 +1,282 @@
+import type { ExtensionContext, Theme } from '@earendil-works/pi-coding-agent';
+import {
+  type Component,
+  Key,
+  matchesKey,
+  type TUI,
+  truncateToWidth,
+} from '@earendil-works/pi-tui';
+import { JEV_STATUS, type JevStatus } from './guard.ts';
+import { JEV_KEY_ENV_VAR, type JevKeySource } from './key.ts';
+
+export const JEV_STATUS_KEY = 'sideroom-jev';
+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>> = {
+  [JEV_STATUS.ready]: 'jev: ready',
+  [JEV_STATUS.noKey]: 'jev: no key (F10)',
+  [JEV_STATUS.quota]: 'jev: out of quota (F10)',
+  [JEV_STATUS.auth]: 'jev: key rejected (F10)',
+  [JEV_STATUS.rateLimited]: 'jev: rate limited',
+  [JEV_STATUS.unavailable]: 'jev: unreachable',
+};
+
+export interface JevKeyActions {
+  readonly store: (apiKey: string) => void;
+  readonly clear: () => void;
+  readonly retry: () => void;
+  readonly origin: () => JevKeySource['origin'] | undefined;
+  readonly usage: () => number;
+  readonly refresh: (ctx: ExtensionContext) => void;
+}
+
+export interface JevKeyController {
+  open(ctx: ExtensionContext): void;
+}
+
+export function statusLabel(
+  status: JevStatus,
+  model?: string,
+  calls = 0,
+): string {
+  const base =
+    status === JEV_STATUS.ready && model !== undefined
+      ? `jev: ready (${model})`
+      : STATUS_LABEL[status];
+  if (calls === 0) {
+    return base;
+  }
+  return `${base} · ${String(calls)} call${calls === 1 ? '' : 's'}`;
+}
+
+export function createJevKeyController(
+  actions: JevKeyActions,
+): JevKeyController {
+  let opening = false;
+
+  return {
+    open(ctx) {
+      if (opening) {
+        return;
+      }
+      if (ctx.mode !== 'tui') {
+        ctx.ui.notify(
+          `Set ${JEV_KEY_ENV_VAR} in the environment: capturing a key needs the terminal.`,
+          'warning',
+        );
+        return;
+      }
+      opening = true;
+      void ctx.ui
+        .custom<void>(
+          (tui, theme, _keybindings, done) =>
+            new JevKeyOverlay(tui, theme, done, actions, ctx),
+          {
+            overlay: true,
+            overlayOptions: {
+              anchor: 'center',
+              width: '70%',
+              minWidth: 44,
+              maxHeight: '60%',
+              visible: (terminalWidth) => terminalWidth >= 60,
+            },
+          },
+        )
+        .finally(() => {
+          opening = false;
+        });
+    },
+  };
+}
+
+// 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;
+  private readonly theme: Theme;
+  private readonly close: () => void;
+  private readonly actions: JevKeyActions;
+  private readonly ctx: ExtensionContext;
+
+  constructor(
+    tui: TUI,
+    theme: Theme,
+    close: () => void,
+    actions: JevKeyActions,
+    ctx: ExtensionContext,
+  ) {
+    this.tui = tui;
+    this.theme = theme;
+    this.close = close;
+    this.actions = actions;
+    this.ctx = ctx;
+  }
+
+  handleInput(keyData: string): void {
+    const pasted = readPastedKey(keyData);
+    if (pasted !== undefined) {
+      this.append(pasted);
+      return;
+    }
+    if (matchesKey(keyData, Key.escape)) {
+      this.close();
+      return;
+    }
+    if (matchesKey(keyData, Key.enter)) {
+      this.save();
+      return;
+    }
+    if (matchesKey(keyData, Key.backspace)) {
+      this.entry = this.entry.slice(0, -1);
+      this.tui.requestRender();
+      return;
+    }
+    if (matchesKey(keyData, CLEAR_KEY)) {
+      this.clearStored();
+      return;
+    }
+    if (isTypedCharacter(keyData)) {
+      this.append(keyData);
+    }
+  }
+
+  private append(text: string): void {
+    if (text.length === 0) {
+      return;
+    }
+    this.entry = `${this.entry}${text}`.slice(0, MAX_KEY_LENGTH);
+    this.tui.requestRender();
+  }
+
+  render(width: number): string[] {
+    const innerWidth = Math.max(1, width - 2);
+    const border = (text: string) => this.theme.fg('border', text);
+    const line = (text: string) => truncateToWidth(text, innerWidth, '…', true);
+    const row = (text: string) => `${border('│')}${line(text)}${border('│')}`;
+
+    const lines = [
+      border(`╭${'─'.repeat(innerWidth)}╮`),
+      row(this.theme.fg('accent', this.theme.bold(' Jev API key '))),
+      border(`├${'─'.repeat(innerWidth)}┤`),
+      row(` ${MASK_CHARACTER.repeat(this.entry.length)}`),
+      row(this.theme.fg('dim', ` source: ${this.originLabel()}`)),
+      row(
+        this.theme.fg(
+          'dim',
+          ` calls this session: ${String(this.actions.usage())}`,
+        ),
+      ),
+      border(`├${'─'.repeat(innerWidth)}┤`),
+      row(
+        this.theme.fg(
+          'dim',
+          ' The key is stored in sideroom.json, never in the session.',
+        ),
+      ),
+      row(
+        this.theme.fg(
+          'dim',
+          ` ${JEV_KEY_ENV_VAR} wins over the file when both are set.`,
+        ),
+      ),
+      border(`├${'─'.repeat(innerWidth)}┤`),
+      row(this.theme.fg('dim', ' Enter save · Ctrl+U clear · Esc close')),
+      border(`╰${'─'.repeat(innerWidth)}╯`),
+    ];
+    return lines;
+  }
+
+  invalidate(): void {}
+
+  private save(): void {
+    const apiKey = this.entry.trim();
+    if (apiKey.length === 0) {
+      return;
+    }
+    this.actions.store(apiKey);
+    this.finish('Jev API key stored.');
+  }
+
+  private clearStored(): void {
+    this.entry = '';
+    this.actions.clear();
+    this.finish('Jev API key cleared.');
+  }
+
+  private finish(message: string): void {
+    this.actions.retry();
+    this.actions.refresh(this.ctx);
+    this.ctx.ui.notify(message, 'info');
+    this.close();
+  }
+
+  private originLabel(): string {
+    const origin = this.actions.origin();
+    if (origin === 'environment') {
+      return `from ${JEV_KEY_ENV_VAR}`;
+    }
+    if (origin === 'config') {
+      return 'stored in sideroom.json';
+    }
+    return 'not configured';
+  }
+}
+
+// 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) {
+    return undefined;
+  }
+  const from = start + PASTE_START.length;
+  const end = keyData.indexOf(PASTE_END, from);
+  const body = end === -1 ? keyData.slice(from) : keyData.slice(from, end);
+  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) {
+    const code = character.codePointAt(0) ?? 0;
+    if (!isControlCode(code) && character !== ' ') {
+      printable += character;
+    }
+  }
+  return printable;
+}
+
+function isTypedCharacter(keyData: string): boolean {
+  if (keyData.length === 0) {
+    return false;
+  }
+  for (const character of keyData) {
+    if (isControlCode(character.codePointAt(0) ?? 0)) {
+      return false;
+    }
+  }
+  return true;
+}

package/extensions/persona/catalog.ts

@@ -32,29 +32,29 @@ export interface VoiceRule {
 }
 
 export const VOICE_RULES: readonly VoiceRule[] = [
+  {
+    id: 'plain-language',
+    instruction:
+      'Explain in plain words: name the subject and goal before the detail, prefer everyday terms over concept jargon (hook, pipeline, registry, resolver, guardrail, invariant) unless the user used them, define any necessary term in one line, and be explicit without repetition. Never write tangled chains such as "the registry resolves the provider through the auth resolver".',
+  },
   {
     id: 'direct',
     instruction:
-      'Be direct and dry. Use short sentences. No preamble or closing summary.',
+      'Be direct and dry. Short sentences. No preamble or closing summary.',
   },
   {
     id: 'no-filler',
     instruction: 'No filler.',
   },
-  {
-    id: 'plain-language',
-    instruction:
-      'Explain plainly and leave no doubt. Name the subject and goal before details, define unfamiliar terms in one line, and be explicit without repetition.',
-  },
   {
     id: 'no-invented-terms',
     instruction:
-      'Name things as they are. Add no intermediate terms, abbreviations, or codenames unless the user asks.',
+      'Name things as they are. Coin no intermediate term, abbreviation, codename, or technical concept word the user did not ask for.',
   },
   {
     id: 'short-prose',
     instruction:
-      'Default to short prose. Use lists or tables only for comparisons or more than three items.',
+      'Default to short prose. Lists or tables only to compare options or list more than three items.',
   },
   {
     id: 'user-language',

package/extensions/persona/guard.ts

@@ -1,10 +1,11 @@
-import { readFileSync } from 'node:fs';
 import {
   type ExtensionAPI,
+  type ExtensionContext,
   isToolCallEventType,
   type ToolCallEvent,
 } from '@earendil-works/pi-coding-agent';
 import { resolveFileToolPath } from '../shared/file-path.ts';
+import { readFileIfExists } from '../shared/read-file.ts';
 import {
   PERSONA_STEER_TYPE,
   type ProhibitionId,
@@ -38,29 +39,41 @@ export interface PersonaGuardState {
   readonly fires: Map<ProhibitionId, number>;
   cleanMutations: number;
   steersThisRun: number;
+  blocksThisRun: number;
 }
 
 export function createPersonaGuardState(): PersonaGuardState {
-  return { fires: new Map(), cleanMutations: 0, steersThisRun: 0 };
+  return {
+    fires: new Map(),
+    cleanMutations: 0,
+    steersThisRun: 0,
+    blocksThisRun: 0,
+  };
 }
 
 export function resetPersonaRun(state: PersonaGuardState): void {
   state.steersThisRun = 0;
+  state.blocksThisRun = 0;
 }
 
 export function registerPersonaGuard(
   pi: ExtensionAPI,
   state: PersonaGuardState,
+  report: (ctx: ExtensionContext) => void,
 ): void {
   pi.on('tool_call', (event, ctx) => {
     const mutation = extractMutation(event, ctx.cwd);
     if (mutation === undefined) {
       return undefined;
     }
-    return applyArtifactOutcome(pi, state, mutation);
+    const blockDecision = applyArtifactOutcome(pi, state, mutation);
+    if (blockDecision !== undefined) {
+      report(ctx);
+    }
+    return blockDecision;
   });
 
-  pi.on('message_end', (event) => {
+  pi.on('message_end', (event, ctx) => {
     if (event.message.role !== 'assistant') {
       return undefined;
     }
@@ -73,6 +86,7 @@ export function registerPersonaGuard(
     }
 
     sendPersonaSteer(pi, state, formatSteer(violations));
+    report(ctx);
     return undefined;
   });
 }
@@ -92,6 +106,7 @@ function applyArtifactOutcome(
     (violation) => !isDegraded(state, violation.prohibition.id),
   );
   if (blocking.length > 0) {
+    state.blocksThisRun += 1;
     for (const violation of blocking) {
       incrementFires(state, violation.prohibition.id);
     }
@@ -126,17 +141,6 @@ function extractMutation(
   return undefined;
 }
 
-function readFileIfExists(path: string): string | undefined {
-  try {
-    return readFileSync(path, 'utf8');
-  } catch (error) {
-    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
-      return undefined;
-    }
-    throw error;
-  }
-}
-
 function isDegraded(state: PersonaGuardState, id: ProhibitionId): boolean {
   return (state.fires.get(id) ?? 0) >= BLOCK_DEGRADE_AFTER;
 }
@@ -156,7 +160,7 @@ function sendPersonaSteer(
   state.steersThisRun += 1;
   pi.sendMessage(
     { customType: PERSONA_STEER_TYPE, content, display: false },
-    { deliverAs: 'steer' },
+    { triggerTurn: true, deliverAs: 'steer' },
   );
 }