@rmrdeveloper/sideroom-pi 8.14.0 → 9.0.0

package/extensions/guidelines/guard.ts

@@ -6,7 +6,13 @@ import {
   isReadToolResult,
   isToolCallEventType,
 } from '@earendil-works/pi-coding-agent';
-import { GUIDELINE_SKILL_PATH, LANGUAGE_GUIDES } from './catalog.ts';
+import {
+  GUIDELINE_SKILL_PATH,
+  GUIDELINES_TOOL_NAME,
+  LANGUAGE_GUIDES,
+  languageGuideFor,
+} from './catalog.ts';
+import type { GuidelinesToolResult } from './execute.ts';
 
 export { GUIDELINE_SKILL_PATH } from './catalog.ts';
 
@@ -19,21 +25,54 @@ interface ReadInput {
 export interface GuidelineReadState {
   skillRead: boolean;
   readonly languageGuidesRead: Set<string>;
+  readonly pendingLoads: Map<string, GuidelinesToolResult>;
 }
 
 export function createGuidelineReadState(): GuidelineReadState {
-  return { skillRead: false, languageGuidesRead: new Set() };
+  return {
+    skillRead: false,
+    languageGuidesRead: new Set(),
+    pendingLoads: new Map(),
+  };
 }
 
 export function resetGuidelineReadState(state: GuidelineReadState): void {
   state.skillRead = false;
   state.languageGuidesRead.clear();
+  state.pendingLoads.clear();
 }
 
 export function registerGuidelineGuard(
   pi: ExtensionAPI,
   state: GuidelineReadState,
 ): void {
+  // This notification follows every tool_result handler, including redactors.
+  pi.on('tool_execution_end', (event, ctx) => {
+    if (event.toolName !== GUIDELINES_TOOL_NAME) {
+      return;
+    }
+    const delivered = state.pendingLoads.get(event.toolCallId);
+    state.pendingLoads.delete(event.toolCallId);
+    const deliveredResult: Partial<GuidelinesToolResult> | undefined =
+      event.result;
+    if (
+      event.isError ||
+      event.parentToolCallId !== undefined ||
+      delivered === undefined ||
+      !Array.isArray(deliveredResult?.content) ||
+      deliveredResult.content.length !== delivered.content.length ||
+      !deliveredResult.content.every(
+        (part, index) =>
+          part.type === 'text' && part.text === delivered.content[index]?.text,
+      )
+    ) {
+      return;
+    }
+    for (const path of delivered.details.paths) {
+      recordGuidelineRead(state, path, ctx.cwd);
+    }
+  });
+
   pi.on('tool_result', (event, ctx) => {
     if (!isReadToolResult(event) || event.isError) {
       return;
@@ -62,7 +101,9 @@ export function registerGuidelineGuard(
     const reason = mutationBlockReason(
       state,
       event.input.path,
-      pi.getActiveTools().includes('read'),
+      pi
+        .getActiveTools()
+        .some((name) => name === 'read' || name === GUIDELINES_TOOL_NAME),
     );
     if (reason === undefined) {
       return;
@@ -113,19 +154,10 @@ export function mutationBlockReason(
     return undefined;
   }
   if (!readToolAvailable) {
-    return `Blocked ${targetPath}: the read tool is inactive, so the guidelines gate cannot be satisfied. Enable read, then read ${requiredPaths.join(' and ')} before retrying the mutation.`;
+    return `Blocked ${targetPath}: the read tool is inactive and sideroom_guidelines is inactive. Enable either tool, then load ${requiredPaths.join(' and ')} before retrying the mutation.`;
   }
 
-  return `Blocked ${targetPath}: read ${requiredPaths.join(' and ')} with the read tool in this agent run, then retry the mutation.`;
-}
-
-function languageGuideFor(path: string): string | undefined {
-  const normalizedPath = stripLeadingAt(path)
-    .replaceAll('\\', '/')
-    .toLowerCase();
-  return LANGUAGE_GUIDES.find(({ extensions }) =>
-    extensions.some((extension) => normalizedPath.endsWith(extension)),
-  )?.path;
+  return `Blocked ${targetPath}: call sideroom_guidelines with path ${JSON.stringify(targetPath)}, or read ${requiredPaths.join(' and ')} in full with the read tool in this agent run, then retry the mutation.`;
 }
 
 const canonicalCatalogPaths = new Map<string, string>();

package/extensions/guidelines/index.ts

@@ -1,4 +1,7 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { GUIDELINES_TOOL_NAME } from './catalog.ts';
+import { executeGuidelines } from './execute.ts';
 import {
   createGuidelineReadState,
   registerGuidelineGuard,
@@ -16,6 +19,34 @@ export default function registerGuidelines(pi: ExtensionAPI): void {
   const readState = createGuidelineReadState();
   registerGuidelineGuard(pi, readState);
 
+  pi.registerTool({
+    name: GUIDELINES_TOOL_NAME,
+    label: 'Sideroom Guidelines',
+    description:
+      'Before write or edit, load the complete Sideroom coding skill and the language guide for the target path. Unsupported languages load only the general skill. Call directly, not from another tool. Reuse loaded guides in this agent run; reload after compaction or a new run. Full reads of the packaged documents through read remain supported.',
+    parameters: Type.Object({
+      path: Type.String({
+        minLength: 1,
+        description:
+          'Path of the file you will change; the file need not exist.',
+      }),
+    }),
+    exposure: 'model-only',
+    executionMode: 'sequential',
+    async execute(toolCallId, { path }, signal) {
+      signal?.throwIfAborted();
+      const loaded = executeGuidelines(path);
+      signal?.throwIfAborted();
+      // Keep an independent receipt: changed or partial tool results cannot
+      // authorize mutations, and resets discard receipts still awaiting delivery.
+      readState.pendingLoads.set(toolCallId, {
+        content: loaded.content.map((part) => ({ ...part })),
+        details: { paths: [...loaded.details.paths] },
+      });
+      return loaded;
+    },
+  });
+
   const reviewState = createReviewState();
   registerReviewGuard(pi, reviewState);
   pi.on('session_start', () => {

package/extensions/guidelines/prompt.ts

@@ -12,10 +12,10 @@ const LANGUAGE_GUIDE_INDEX = LANGUAGE_GUIDES.map(
 ).join('; ');
 
 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:
+Before write or edit, call sideroom_guidelines with the target path. Reuse loaded guides in this run; reload after compaction. Alternatively, use the read tool without offset or limit to load 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.`;
+Only successful loads without truncation count. Until all required documents are loaded, 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

@@ -14,7 +14,7 @@ import {
 export const REVIEW_STEER_TYPE = 'sideroom-guidelines-review';
 
 export const REVIEW_STEER =
-  'Finish any remaining requested implementation before reviewing. Review the changes this run introduced against the loaded Sideroom language guide: fix only demonstrated violations caused by those changes, preserving all requested requirements and existing behavior. KISS and YAGNI do not justify removing required error handling, compatibility, or tests. Do not refactor unrelated code. Then run the relevant formatter, linter, type checks, and tests. If the guide is no longer in context, re-read it in full first.';
+  'Finish any remaining requested implementation before reviewing. Review the changes this run introduced against the loaded Sideroom language guide: fix only demonstrated violations caused by those changes, preserving all requested requirements and existing behavior. KISS and YAGNI do not justify removing required error handling, compatibility, or tests. Include rule 20, Decomposition by intent: names and contracts should separate orchestration from coherent implementation details, even with one caller. Do not split solely for line count or separate tightly coupled steps into shared mutable state, excessive parameters, or functions that must be read together. Do not refactor unrelated code. 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 const WORKFLOW_REVIEW_STEER =
   'Verify the semantic notes below against the visible evidence and the questionnaire or task contract. Correct only demonstrated ambiguity or contradictions; respect user answers and ask again only when clarification is necessary. Missing evidence is not proof of unfinished work. Do not create unrelated implementation work. Run project checks only if code changes.';

package/extensions/jev/model.ts

@@ -186,6 +186,19 @@ export const JEV_RULES: readonly JevRule[] = [
       },
     },
   },
+  {
+    id: 'decomposition-by-intent',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'In `change.addedLines`, does the changed function obscure orchestration with a coherent implementation operation that a named function with a clear contract would make understandable without reading its implementation, or does a new split make tightly coupled steps harder to understand? Require the operation and its surrounding orchestration or helper caller to be visible in `file.body` or `context.files`; do not infer unseen bodies. One caller is sufficient for a useful extraction. Never flag function length alone or require a split that introduces shared mutable state, excessive parameters, or functions that must be read together.',
+      criteria: {
+        true: 'Visible bodies show added implementation details obscuring the caller flow, with a coherent extractable operation and a clear independent contract, or a new split demonstrably harms comprehension by separating tightly coupled steps',
+        false:
+          'Names and contracts already convey the flow, coupled steps belong together, length is the only signal, or evidence is insufficient',
+      },
+    },
+  },
   {
     id: 'unnecessary-abstraction',
     question: {

package/extensions/visual-context/broker.ts

@@ -106,6 +106,7 @@ export async function startBroker({
       publish();
     });
     socket.on('message', (bytes, binary) => {
+      let selectionId: string | undefined;
       try {
         const message = parseEnvelope(bytes.toString(), binary);
         if (!peer.role) {
@@ -191,10 +192,14 @@ export async function startBroker({
           }
           throw new Error('Invalid Pi message.');
         }
-        if (
-          message.type !== MESSAGE_TYPE.selection ||
-          !Check(SessionDescriptorSchema, message.target)
-        ) {
+        if (message.type !== MESSAGE_TYPE.selection) {
+          throw new Error(
+            'Choose a destination session in the browser companion.',
+          );
+        }
+        const selection = parseSelection(message.selection);
+        selectionId = selection.id;
+        if (!Check(SessionDescriptorSchema, message.target)) {
           throw new Error(
             'Choose a destination session in the browser companion.',
           );
@@ -218,7 +223,6 @@ export async function startBroker({
             'Pi is still processing selections. Try again shortly.',
           );
         }
-        const selection = parseSelection(message.selection);
         peer.lastSelectionAt = Date.now();
         const requestId = randomUUID();
         const timer = setTimeout(() => {
@@ -249,7 +253,11 @@ export async function startBroker({
           cause instanceof Error
             ? cause
             : new Error('Cannot route browser selection.', { cause });
-        send(socket, { type: MESSAGE_TYPE.error, message: error.message });
+        send(socket, {
+          type: MESSAGE_TYPE.error,
+          id: selectionId,
+          message: error.message,
+        });
         if (!peer.role) {
           socket.close(1008, 'Invalid pairing');
         }

package/extensions/visual-context/compiler-config.ts

@@ -0,0 +1,103 @@
+export const CONFIG_KINDS = [
+  'astro',
+  'nuxt',
+  'next',
+  'vite',
+  'webpack',
+  'rspack',
+] as const;
+export type ConfigKind = (typeof CONFIG_KINDS)[number];
+export const INSPECTOR_PACKAGE = 'code-inspector-plugin';
+export const INSPECTOR_VERSION = '2.0.9';
+
+export const COMPILER_IDENTIFIER = 'sideroomSourceLocations';
+export const CORE_PACKAGE = '@code-inspector/core';
+export const LOADER_PACKAGE = '@code-inspector/webpack';
+export const METADATA_LOADER = `${LOADER_PACKAGE}/dist/loader.js`;
+
+export function compilerPackage(kind: ConfigKind): string {
+  return kind === 'vite' || kind === 'astro' || kind === 'nuxt'
+    ? CORE_PACKAGE
+    : LOADER_PACKAGE;
+}
+
+interface CompilerIntegrationInput {
+  readonly kind: ConfigKind;
+  readonly commonjs: boolean;
+  readonly typescript: boolean;
+}
+
+export function compilerIntegration({
+  kind,
+  commonjs,
+  typescript,
+}: CompilerIntegrationInput): string {
+  const importBinding = (binding: string, packageName: string): string =>
+    commonjs
+      ? `const { ${binding.replaceAll(' as ', ': ')} } = require('${packageName}');`
+      : `import { ${binding} } from '${packageName}';`;
+  if (compilerPackage(kind) === CORE_PACKAGE) {
+    const positionTypes = typescript
+      ? 'source: string, id: string'
+      : 'source, id';
+    const constant = typescript ? ' as const' : '';
+    const astroLoad =
+      kind === 'astro'
+        ? `
+async load(${typescript ? 'id: string' : 'id'}) {
+  if (!id.endsWith('.astro') || id.includes('/node_modules/')) {
+    return;
+  }
+  return sideroomTransform({ content: await sideroomReadFile(id, 'utf8'), filePath: id, fileType: 'astro', escapeTags: [/^[A-Z]/, /[.:-]/], pathType: 'absolute' });
+},`
+        : '';
+    return `${importBinding('transformCode as sideroomTransform', CORE_PACKAGE)}
+${kind === 'astro' ? importBinding('readFile as sideroomReadFile', 'node:fs/promises') : ''}
+
+function ${COMPILER_IDENTIFIER}() {
+  return {
+    name: 'sideroom-source-locations',
+    enforce: 'pre'${constant},
+    apply: 'serve'${constant},
+    async transform(${positionTypes}) {
+      const [file, query] = id.split('?');
+      if (!file || query || file.includes('/node_modules/')) {
+        return;
+      }
+      const fileType = /\\.(jsx|tsx|js|ts|mjs|mts)$/.test(file) ? 'jsx' : file.endsWith('.vue') ? 'vue' : file.endsWith('.svelte') ? 'svelte' : undefined;
+      if (!fileType) {
+        return;
+      }
+      return sideroomTransform({ content: source, filePath: file, fileType, escapeTags: [/^[A-Z]/, /[.:-]/], pathType: 'absolute' });
+    },${astroLoad}
+  };
+}
+`;
+  }
+  const imports = commonjs
+    ? ''
+    : `${importBinding('createRequire as sideroomCreateRequire', 'node:module')}
+const sideroomRequire = sideroomCreateRequire(import.meta.url);`;
+  const compilerType = typescript
+    ? 'compiler: { options: { mode?: string; module?: { rules?: unknown[] } } }'
+    : 'compiler';
+  return `${imports}
+function ${COMPILER_IDENTIFIER}() {
+  return {
+    apply(${compilerType}) {
+      if (compiler.options.mode !== 'development') {
+        return;
+      }
+      compiler.options.module ??= {};
+      compiler.options.module.rules ??= [];
+      compiler.options.module.rules.unshift({
+        test: /\\.(jsx|tsx|js|ts|mjs|mts|vue|svelte)$/,
+        exclude: /node_modules/,
+        enforce: 'pre',
+        use: [{ loader: ${commonjs ? 'require' : 'sideroomRequire'}.resolve('${METADATA_LOADER}'), options: { pathType: 'absolute' } }],
+      });
+    },
+  };
+}
+`;
+}