@rmrdeveloper/sideroom-pi 8.8.0 → 8.9.0

package/extensions/jev/ui.ts

@@ -0,0 +1,281 @@
+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.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' },
   );
 }
 

package/extensions/persona/index.ts

@@ -11,7 +11,7 @@ import {
   registerPersonaGuard,
   resetPersonaRun,
 } from './guard.ts';
-import { PERSONA_STATUS_LABEL } from './model.ts';
+import { personaStatusLabel } from './model.ts';
 import { appendPersonaReminder } from './prompt.ts';
 
 export const PERSONA_DESCRIPTION =
@@ -22,7 +22,16 @@ export const PERSONA_PROMPT_SNIPPET = 'Read the active Sideroom persona.';
 // Pi loads extensions/*/index.ts through export default.
 export default function registerPersona(pi: ExtensionAPI): void {
   const state = createPersonaGuardState();
-  registerPersonaGuard(pi, state);
+  const publishStatus = (ctx: ExtensionContext): void => {
+    if (!ctx.hasUI) {
+      return;
+    }
+    ctx.ui.setStatus(
+      PERSONA_STATUS_KEY,
+      personaStatusLabel(state.blocksThisRun, state.steersThisRun),
+    );
+  };
+  registerPersonaGuard(pi, state, publishStatus);
 
   pi.on('session_start', (_event, ctx) => publishStatus(ctx));
 
@@ -68,10 +77,3 @@ export default function registerPersona(pi: ExtensionAPI): void {
     },
   });
 }
-
-function publishStatus(ctx: ExtensionContext): void {
-  if (!ctx.hasUI) {
-    return;
-  }
-  ctx.ui.setStatus(PERSONA_STATUS_KEY, PERSONA_STATUS_LABEL);
-}

package/extensions/persona/model.ts

@@ -20,7 +20,23 @@ export interface PersonaToolDetails {
   readonly prohibitions: readonly string[];
 }
 
-export const PERSONA_STATUS_LABEL = `persona: direct, ${String(PROHIBITIONS.length)} prohibitions`;
+export function personaStatusLabel(blocks: number, steers: number): string {
+  const counts = [
+    countLabel(blocks, 'block'),
+    countLabel(steers, 'steer'),
+  ].filter((count) => count.length > 0);
+  if (counts.length === 0) {
+    return 'persona: direct';
+  }
+  return `persona: direct · ${counts.join(' · ')}`;
+}
+
+function countLabel(count: number, noun: string): string {
+  if (count === 0) {
+    return '';
+  }
+  return `${String(count)} ${noun}${count === 1 ? '' : 's'}`;
+}
 
 export function personaToolDetails(): PersonaToolDetails {
   return {
@@ -82,7 +98,7 @@ export function formatSteer(
       (violation) =>
         `- ${violation.prohibition.rule} Found: "${violation.excerpt}"`,
     ),
-    'Rewrite it plainly: name the subject and goal before details, without ambiguity or repetition.',
+    'Rewrite in plain words: subject and goal first, everyday terms, no concept jargon the user did not use.',
   ].join('\n');
 }
 

package/extensions/persona/prompt.ts

@@ -15,10 +15,19 @@ 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: Enable the flag to skip cache (enableCache). Don't: The registry resolves the provider through the auth resolver pipeline.",
+  "Do: This runs when the session closes (session_save). Don't: The lifecycle hook tears down session-scoped resources via the cleanup path.",
+] as const;
+
 export const PERSONA_REMINDER = `${PERSONA_REMINDER_HEADING}
 Voice: ${VOICE_SUMMARY}
 Never: ${PROHIBITION_SUMMARY}
 ${ENFORCEMENT_SUMMARY}
+Examples:
+${PERSONA_EXAMPLES.join('\n')}
 Full guide: call ${PERSONA_TOOL_NAME} or read ${PERSONA_SKILL_PATH}.`;
 
 export function appendPersonaReminder(systemPrompt: string): string {

package/extensions/rules/guard.ts

@@ -1,4 +1,3 @@
-import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import {
   type ExtensionAPI,
@@ -7,6 +6,7 @@ import {
   isWriteToolResult,
   type ToolCallEvent,
 } from '@earendil-works/pi-coding-agent';
+import { readFileIfExists } from '../shared/read-file.ts';
 import { languageForPath, type RuleId, SEVERITY } from './catalog.ts';
 import { evaluateAddedLines } from './checks.ts';
 import {
@@ -164,21 +164,6 @@ function extractEdit(
   return { path, language: languageForPath(path), lines };
 }
 
-function readFileIfExists(path: string): string | undefined {
-  try {
-    return readFileSync(path, 'utf8');
-  } catch (error) {
-    if (isMissingFile(error)) {
-      return undefined;
-    }
-    throw error;
-  }
-}
-
-function isMissingFile(error: unknown): boolean {
-  return error instanceof Error && 'code' in error && error.code === 'ENOENT';
-}
-
 function isDegraded(state: RulesState, ruleId: RuleId): boolean {
   return (state.fires.get(ruleId) ?? 0) >= BLOCK_DEGRADE_AFTER;
 }

package/extensions/shared/read-file.ts

@@ -0,0 +1,18 @@
+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');
+  } catch (error) {
+    if (isMissingFile(error)) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+export function isMissingFile(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}

package/extensions/todo/guards.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "8.8.0",
+  "version": "8.9.0",
   "description": "Pi coding-agent package that asks clarifying questions, shows a live todo board, enforces coding guidelines, and will not call it done while your checks are red.",
   "type": "module",
   "files": [

package/skills/sideroom-persona/SKILL.md

@@ -22,20 +22,25 @@ needs the full persona instead of the injected reminder.
 
 | # | Rule | Do | Don't |
 | --- | --- | --- | --- |
-| 1 | Direct and dry | `The guard blocks the write. Fix the emoji and retry.` | `I'd be happy to help with that! Let's take a look together.` |
-| 2 | No filler | Start with the answer. | `Before we dive in…`, `As I mentioned earlier…`, `To summarize what I just said…` |
-| 3 | Plain, never in doubt | `Persona controls how the agent talks. Its goal is to keep every answer direct and clear.` | `The voice layer hooks the persona surface and normalizes register.` |
+| 1 | Plain, never in doubt | `Enable the flag to skip cache (enableCache).` | `The registry resolves the provider through the auth resolver pipeline.` |
+| 2 | Direct and dry | `The guard blocks the write. Fix the emoji and retry.` | `I'd be happy to help with that! Let's take a look together.` |
+| 3 | No filler | Start with the answer. | `Before we dive in…`, `As I mentioned earlier…`, `To summarize what I just said…` |
 | 4 | No invented terms | `the file the mutation adds` | `the artifact delta` (when the user never asked for that name) |
 | 5 | Short prose | Prose for one or two points. | A three-bullet list for a single sentence. |
 | 6 | User's language | Answer in the language and variant the user wrote in. | A Spanish question answered in English. |
 
-### Plain means no doubt, not more words
+### Plain means everyday words, not more words
 
-Rule 3 outranks brevity for clarity, and rule 2 outranks rule 3 for length.
-Concretely: name the subject and the goal **before** the detail, define an
-unfamiliar term in one line, then stop. Being explicit is not a licence to
+Rule 1 outranks brevity for clarity, and rule 3 outranks rule 1 for length.
+Concretely: name the subject and the goal **before** the detail, use everyday
+words instead of concept jargon (`hook`, `pipeline`, `registry`, `resolver`,
+`guardrail`, `invariant`) unless the user already used them, define any
+necessary term in one line, then stop. Being explicit is not a licence to
 repeat yourself, restate the question, or explain the same point twice.
 
+- Do: `This runs when the session closes. In code: \`session_save\`.`
+- Don't: `The lifecycle hook tears down session-scoped resources via the
+  cleanup path.`
 - Do: `The persona reminder is injected on every turn, so it survives
   compaction. That is why switching profiles would be pointless here.`
 - Don't: `What I'm saying is that the reminder gets injected, and since it's
@@ -72,7 +77,9 @@ dead-locked.
 ### What steering means
 
 The extension sends a corrective steer after a degraded artifact block or a
-prohibited assistant message. At most three steers are sent per agent run.
+prohibited assistant message. Steers use `triggerTurn: true` so they reach the
+model even when the run is already idle. At most three steers are sent per
+agent run.
 
 ## Boundaries