@rmrdeveloper/sideroom-pi 8.8.0 → 8.10.0

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/file-path.ts

@@ -1,6 +1,6 @@
 import { realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { isAbsolute, join, resolve } from 'node:path';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const FILE_URL_PREFIX = 'file://';
@@ -29,6 +29,31 @@ export function resolveFileToolPath(
   return realpathOr(absolutePath);
 }
 
+// A file that does not exist yet keeps its unresolved path, so it is matched
+// against the literal working directory as well as the canonical one.
+export function projectRelativePath(
+  cwd: string,
+  absolutePath: string,
+): string | undefined {
+  const literalRoot = resolve(cwd);
+  for (const root of new Set([realpathOr(literalRoot), literalRoot])) {
+    const relativePath = relative(root, absolutePath);
+    if (isInsideRoot(relativePath)) {
+      return relativePath;
+    }
+  }
+  return undefined;
+}
+
+function isInsideRoot(relativePath: string): boolean {
+  return (
+    relativePath.length > 0 &&
+    relativePath !== '..' &&
+    !relativePath.startsWith(`..${sep}`) &&
+    !isAbsolute(relativePath)
+  );
+}
+
 function normalizeFileToolPath(path: string): string {
   const normalizedSpaces = path.replace(UNICODE_SPACES, ' ');
   const withoutAtPrefix = normalizedSpaces.startsWith('@')

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/shared/review-note.ts

@@ -0,0 +1,14 @@
+export const REVIEW_NOTE_EVENT = 'sideroom:review-note';
+
+export interface ReviewNote {
+  readonly text: string;
+}
+
+export function isReviewNote(value: unknown): value is ReviewNote {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'text' in value &&
+    typeof value.text === 'string'
+  );
+}

package/extensions/shared/settle.ts

@@ -0,0 +1,50 @@
+import type {
+  AgentBeforeSettleEvent,
+  AgentBeforeSettleEventResult,
+  InputEvent,
+  InputSource,
+} from '@earendil-works/pi-coding-agent';
+
+const COMPLETED_OUTCOME = 'completed';
+const USER_ROLE = 'user';
+const CUSTOM_MESSAGE_ENTRY = 'custom_message';
+const USER_INPUT_SOURCES: ReadonlySet<InputSource> = new Set([
+  'interactive',
+  'rpc',
+]);
+
+// A message typed while the agent runs joins the current run as a steer or
+// follow-up; only input that arrives idle opens a new turn.
+export function startsUserTurn(event: InputEvent): boolean {
+  return (
+    USER_INPUT_SOURCES.has(event.source) &&
+    event.streamingBehavior === undefined
+  );
+}
+
+// An aborted run is the user stopping the agent, an errored run has nothing
+// worth reviewing, and a pending user message already decides what comes next.
+export function acceptsSettleSteer(event: AgentBeforeSettleEvent): boolean {
+  if (event.outcome !== COMPLETED_OUTCOME) {
+    return false;
+  }
+  return !event.context.pendingMessages.some(
+    (message) => message.role === USER_ROLE,
+  );
+}
+
+// Handlers chain on agent_before_settle, so keep the entries earlier handlers
+// proposed; replacing them would drop another extension's steer.
+export function withHiddenSteer(
+  event: AgentBeforeSettleEvent,
+  customType: string,
+  content: string,
+): AgentBeforeSettleEventResult {
+  return {
+    entries: [
+      ...event.entries,
+      { type: CUSTOM_MESSAGE_ENTRY, customType, content, display: false },
+    ],
+    continue: true,
+  };
+}

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.10.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": [
@@ -89,8 +89,8 @@
     "@changesets/cli": "^3.0.2",
     "@commitlint/cli": "^21.2.2",
     "@commitlint/config-conventional": "^21.2.2",
-    "@earendil-works/pi-coding-agent": "0.84.4",
-    "@earendil-works/pi-tui": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.87.1",
+    "@earendil-works/pi-tui": "0.87.1",
     "@types/node": "^22.20.1",
     "typebox": "1.3.7",
     "typescript": "^5.6.0"

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,12 @@ 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. Both moments happen while the agent is working, so
+the steer travels through `pi.sendMessage` with `{ triggerTurn: true, deliverAs:
+'steer' }` and joins the current run. A steer sent after the run ended belongs
+to the guidelines review and the walkthrough offer, which append a
+`custom_message` entry on `agent_before_settle` instead.
+At most three steers are sent per agent run.
 
 ## Boundaries