@rmrdeveloper/sideroom-pi 8.7.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/monorepo-skills/flags.ts

@@ -0,0 +1,9 @@
+const END_OF_OPTIONS = '--';
+const NO_SKILLS_FLAGS = new Set(['--no-skills', '-ns']);
+
+export function areSkillsDisabled(argv: readonly string[]): boolean {
+  const endOfOptions = argv.indexOf(END_OF_OPTIONS);
+  const optionArguments =
+    endOfOptions === -1 ? argv : argv.slice(0, endOfOptions);
+  return optionArguments.some((argument) => NO_SKILLS_FLAGS.has(argument));
+}

package/extensions/monorepo-skills/index.ts

@@ -0,0 +1,36 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+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;
+
+  pi.on('resources_discover', (event, ctx) => {
+    hasMonorepoSkills = false;
+    if (!ctx.isProjectTrusted() || areSkillsDisabled(process.argv)) {
+      return;
+    }
+
+    const skillPaths = findMonorepoSkillPaths(event.cwd);
+    if (skillPaths.length === 0) {
+      return;
+    }
+
+    hasMonorepoSkills = true;
+    return { skillPaths };
+  });
+
+  pi.on('before_agent_start', (event) => {
+    if (!hasMonorepoSkills) {
+      return;
+    }
+
+    const systemPrompt = appendMonorepoSkillsNote(event.systemPrompt);
+    if (systemPrompt === event.systemPrompt) {
+      return;
+    }
+    return { systemPrompt };
+  });
+}

package/extensions/monorepo-skills/prompt.ts

@@ -0,0 +1,14 @@
+export const MONOREPO_SKILLS_NOTE_HEADING = 'Sideroom monorepo skills:';
+
+export const MONOREPO_SKILLS_NOTE = `${MONOREPO_SKILLS_NOTE_HEADING}
+Some available skills come from child folders of this repository. When skills cover the same work, prefer the skill whose location is inside the folder you are editing.`;
+
+export function appendMonorepoSkillsNote(systemPrompt: string): string {
+  if (systemPrompt.includes(MONOREPO_SKILLS_NOTE_HEADING)) {
+    return systemPrompt;
+  }
+  if (systemPrompt.length === 0) {
+    return MONOREPO_SKILLS_NOTE;
+  }
+  return `${systemPrompt}\n\n${MONOREPO_SKILLS_NOTE}`;
+}

package/extensions/monorepo-skills/scan.ts

@@ -0,0 +1,225 @@
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import ignore from 'ignore';
+
+const MAX_CHILD_DEPTH = 3;
+const IGNORE_FILE_NAMES = ['.gitignore', '.ignore', '.fdignore'] as const;
+const NODE_MODULES_DIRECTORY = 'node_modules';
+const PI_DIRECTORY = '.pi';
+const AGENTS_DIRECTORY = '.agents';
+const SKILLS_DIRECTORY = 'skills';
+const SKILL_FILE_NAME = 'SKILL.md';
+const MARKDOWN_EXTENSION = '.md';
+
+export function findMonorepoSkillPaths(cwd: string): string[] {
+  const rootDirectory = resolve(cwd);
+  const childDirectories = collectChildDirectories(
+    rootDirectory,
+    rootDirectory,
+    0,
+    [],
+  );
+  childDirectories.sort((left, right) =>
+    compareText(relative(rootDirectory, left), relative(rootDirectory, right)),
+  );
+
+  const skillPaths: string[] = [];
+  for (const childDirectory of childDirectories) {
+    const piSkillsDirectory = join(
+      childDirectory,
+      PI_DIRECTORY,
+      SKILLS_DIRECTORY,
+    );
+    if (isDirectory(piSkillsDirectory)) {
+      skillPaths.push(piSkillsDirectory);
+    }
+
+    const agentsSkillsDirectory = join(
+      childDirectory,
+      AGENTS_DIRECTORY,
+      SKILLS_DIRECTORY,
+    );
+    if (isDirectory(agentsSkillsDirectory)) {
+      skillPaths.push(...collectAgentsSkillPaths(agentsSkillsDirectory));
+    }
+  }
+  return skillPaths;
+}
+
+function collectChildDirectories(
+  directory: string,
+  rootDirectory: string,
+  depth: number,
+  inheritedIgnorePatterns: readonly string[],
+): string[] {
+  if (depth >= MAX_CHILD_DEPTH) {
+    return [];
+  }
+
+  const ignorePatterns = [
+    ...inheritedIgnorePatterns,
+    ...readIgnoreRules(directory, rootDirectory),
+  ];
+  const ignoreMatcher = ignore().add(ignorePatterns);
+  const childDirectories: string[] = [];
+  for (const entry of readDirectoryEntries(directory)) {
+    if (!entry.isDirectory() || isTraversalDirectory(entry.name)) {
+      continue;
+    }
+
+    const childDirectory = join(directory, entry.name);
+    const relativeChild = toPosixPath(relative(rootDirectory, childDirectory));
+    if (ignoreMatcher.ignores(`${relativeChild}/`)) {
+      continue;
+    }
+
+    childDirectories.push(
+      childDirectory,
+      ...collectChildDirectories(
+        childDirectory,
+        rootDirectory,
+        depth + 1,
+        ignorePatterns,
+      ),
+    );
+  }
+  return childDirectories;
+}
+
+function collectAgentsSkillPaths(skillsDirectory: string): string[] {
+  return collectAgentsSkillPathsFromDirectory(
+    skillsDirectory,
+    skillsDirectory,
+    [],
+  );
+}
+
+function collectAgentsSkillPathsFromDirectory(
+  directory: string,
+  rootDirectory: string,
+  inheritedIgnorePatterns: readonly string[],
+): string[] {
+  const ignorePatterns = [
+    ...inheritedIgnorePatterns,
+    ...readIgnoreRules(directory, rootDirectory),
+  ];
+  const ignoreMatcher = ignore().add(ignorePatterns);
+  const entries = readDirectoryEntries(directory);
+  const declaredSkill = entries.find((entry) => {
+    if (entry.name !== SKILL_FILE_NAME || !entry.isFile()) {
+      return false;
+    }
+    const relativeSkill = toPosixPath(
+      relative(rootDirectory, join(directory, entry.name)),
+    );
+    return !ignoreMatcher.ignores(relativeSkill);
+  });
+  if (declaredSkill) {
+    return [join(directory, declaredSkill.name)];
+  }
+
+  const skillPaths: string[] = [];
+  for (const entry of entries) {
+    if (isTraversalDirectory(entry.name)) {
+      continue;
+    }
+
+    const entryPath = join(directory, entry.name);
+    const relativeEntry = toPosixPath(relative(rootDirectory, entryPath));
+    if (entry.isFile()) {
+      if (
+        directory !== rootDirectory &&
+        entry.name.endsWith(MARKDOWN_EXTENSION) &&
+        !ignoreMatcher.ignores(relativeEntry)
+      ) {
+        skillPaths.push(entryPath);
+      }
+      continue;
+    }
+    if (!entry.isDirectory() || ignoreMatcher.ignores(`${relativeEntry}/`)) {
+      continue;
+    }
+    skillPaths.push(
+      ...collectAgentsSkillPathsFromDirectory(
+        entryPath,
+        rootDirectory,
+        ignorePatterns,
+      ),
+    );
+  }
+  return skillPaths;
+}
+
+function readIgnoreRules(directory: string, rootDirectory: string): string[] {
+  const relativeDirectory = relative(rootDirectory, directory);
+  const prefix = relativeDirectory ? `${toPosixPath(relativeDirectory)}/` : '';
+  const ignorePatterns: string[] = [];
+
+  for (const fileName of IGNORE_FILE_NAMES) {
+    const ignorePath = join(directory, fileName);
+    if (!existsSync(ignorePath)) {
+      continue;
+    }
+
+    ignorePatterns.push(
+      ...readFileSync(ignorePath, 'utf8')
+        .split(/\r?\n/)
+        .map((line) => prefixIgnorePattern(line, prefix))
+        .filter((pattern): pattern is string => pattern !== undefined),
+    );
+  }
+  return ignorePatterns;
+}
+
+function prefixIgnorePattern(line: string, prefix: string): string | undefined {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) {
+    return undefined;
+  }
+  if (trimmed.startsWith('#') && !trimmed.startsWith('\\#')) {
+    return undefined;
+  }
+
+  let pattern = line;
+  let negated = false;
+  if (pattern.startsWith('!')) {
+    negated = true;
+    pattern = pattern.slice(1);
+  } else if (pattern.startsWith('\\!')) {
+    pattern = pattern.slice(1);
+  }
+  if (pattern.startsWith('/')) {
+    pattern = pattern.slice(1);
+  }
+
+  const prefixed = prefix ? `${prefix}${pattern}` : pattern;
+  return negated ? `!${prefixed}` : prefixed;
+}
+
+function readDirectoryEntries(directory: string) {
+  return readdirSync(directory, { withFileTypes: true }).sort((left, right) =>
+    compareText(left.name, right.name),
+  );
+}
+
+function isDirectory(path: string): boolean {
+  return existsSync(path) && lstatSync(path).isDirectory();
+}
+
+function isTraversalDirectory(name: string): boolean {
+  return name.startsWith('.') || name === NODE_MODULES_DIRECTORY;
+}
+
+function toPosixPath(path: string): string {
+  return path.split(sep).join('/');
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) {
+    return -1;
+  }
+  if (left > right) {
+    return 1;
+  }
+  return 0;
+}

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' },
   );
 }