@rmrdeveloper/sideroom-pi 8.11.0 → 8.13.0

package/assets/visual-context/browser/content.js

@@ -0,0 +1,198 @@
+(() => {
+  const INSPECTOR_KEY = '__sideroomVisualInspector';
+  if (globalThis[INSPECTOR_KEY]) {
+    return;
+  }
+  const MAX_TEXT = 160;
+  const MAX_CLASSES = 32;
+  const MAX_ANCESTORS = 4;
+  const BORDER = '#ffb340';
+  let active = false;
+  let root;
+  let box;
+  let caption;
+  let exitHint = 'Esc to exit';
+
+  function clean(text) {
+    return text
+      .split('')
+      .map((character) =>
+        character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127
+          ? ' '
+          : character,
+      )
+      .join('')
+      .replace(/\s+/gu, ' ')
+      .trim()
+      .slice(0, MAX_TEXT);
+  }
+
+  function describe(element) {
+    return {
+      tag: element.localName,
+      elementId: clean(element.id ?? ''),
+      classes: [...element.classList].slice(0, MAX_CLASSES).map(clean),
+    };
+  }
+
+  function visibleText(element) {
+    if (element.closest('input,textarea,select,[contenteditable]')) {
+      return '';
+    }
+    const clone = element.cloneNode(true);
+    for (const child of clone.querySelectorAll(
+      'script,style,input,textarea,select,[contenteditable],[hidden]',
+    )) {
+      child.remove();
+    }
+    return clean(clone.textContent ?? '');
+  }
+
+  function selectedElement(event) {
+    return event
+      .composedPath()
+      .find((node) => node instanceof Element && node !== root);
+  }
+
+  function highlight(event) {
+    const element = selectedElement(event);
+    if (!active || !element || element === document.documentElement) {
+      return;
+    }
+    const bounds = element.getBoundingClientRect();
+    Object.assign(box.style, {
+      left: `${bounds.left}px`,
+      top: `${bounds.top}px`,
+      width: `${bounds.width}px`,
+      height: `${bounds.height}px`,
+    });
+    caption.textContent = `${element.localName} · click to attach · ${exitHint}`;
+  }
+
+  function intercept(event) {
+    if (active) {
+      event.preventDefault();
+      event.stopImmediatePropagation();
+    }
+  }
+
+  async function select(event) {
+    if (!active || !event.isTrusted) {
+      return;
+    }
+    intercept(event);
+    const element = selectedElement(event);
+    if (!element || element === root) {
+      return;
+    }
+    const ancestors = [];
+    let parent = element.parentElement;
+    while (parent && ancestors.length < MAX_ANCESTORS) {
+      ancestors.push(describe(parent));
+      parent = parent.parentElement;
+    }
+    const selection = {
+      id: crypto.randomUUID(),
+      page: `${location.origin}${location.pathname}`,
+      element: describe(element),
+      text: visibleText(element),
+      ancestors,
+    };
+    caption.textContent = 'Sending selection to Pi…';
+    try {
+      const response = await chrome.runtime.sendMessage({
+        action: 'selection',
+        selection,
+      });
+      if (!response.ok) {
+        throw new Error(response.message);
+      }
+    } catch (cause) {
+      if (caption) {
+        caption.textContent = cause.message;
+      }
+    }
+  }
+
+  function keydown(event) {
+    if (event.key === 'Escape') {
+      intercept(event);
+      stop();
+      chrome.runtime.sendMessage({ action: 'stopped' }).catch((cause) => {
+        console.error('Sideroom inspector could not report its exit:', cause);
+      });
+    }
+  }
+
+  function start(shortcut) {
+    stop();
+    exitHint = shortcut ? `Esc or ${shortcut} to exit` : 'Esc to exit';
+    active = true;
+    root = document.createElement('div');
+    root.setAttribute('data-sideroom-inspector', '');
+    Object.assign(root.style, {
+      position: 'fixed',
+      inset: '0',
+      zIndex: '2147483647',
+      pointerEvents: 'none',
+    });
+    const shadow = root.attachShadow({ mode: 'closed' });
+    box = document.createElement('div');
+    Object.assign(box.style, {
+      position: 'fixed',
+      boxSizing: 'border-box',
+      border: `2px solid ${BORDER}`,
+      background: 'rgba(255,179,64,.08)',
+    });
+    caption = document.createElement('div');
+    caption.setAttribute('role', 'status');
+    caption.setAttribute('aria-live', 'polite');
+    caption.textContent = `Select an element · ${exitHint}`;
+    Object.assign(caption.style, {
+      position: 'fixed',
+      bottom: '16px',
+      left: '16px',
+      maxWidth: 'calc(100vw - 32px)',
+      padding: '10px 14px',
+      background: '#131211',
+      color: '#f2ede3',
+      border: `1px solid ${BORDER}`,
+      font: '13px ui-monospace, monospace',
+    });
+    shadow.append(box, caption);
+    document.documentElement.append(root);
+    window.addEventListener('pointermove', highlight, true);
+    window.addEventListener('pointerdown', intercept, true);
+    window.addEventListener('mousedown', intercept, true);
+    window.addEventListener('click', select, true);
+    window.addEventListener('keydown', keydown, true);
+    window.addEventListener('pagehide', stop);
+  }
+
+  function stop() {
+    active = false;
+    root?.remove();
+    root = undefined;
+    box = undefined;
+    caption = undefined;
+    window.removeEventListener('pointermove', highlight, true);
+    window.removeEventListener('pointerdown', intercept, true);
+    window.removeEventListener('mousedown', intercept, true);
+    window.removeEventListener('click', select, true);
+    window.removeEventListener('keydown', keydown, true);
+    window.removeEventListener('pagehide', stop);
+  }
+
+  chrome.runtime.onMessage.addListener((message) => {
+    if (message.action === 'start') {
+      start(message.shortcut);
+    }
+    if (message.action === 'stop') {
+      stop();
+    }
+    if (message.action === 'receipt' && caption) {
+      caption.textContent = message.message;
+    }
+  });
+  globalThis[INSPECTOR_KEY] = { stop };
+})();

package/assets/visual-context/browser/icons/README.md

@@ -0,0 +1,9 @@
+# Browser icon
+
+White `S` on opaque black, rendered with **Archivo Variable**, the text family
+in Sideroom's `DESIGN.md` and `site/src/styles/site.css`. Weight: 700. Source:
+`site/node_modules/@fontsource-variable/archivo/files/archivo-latin-wght-normal.woff2`.
+
+The PNGs are 16, 32, 48 and 128 pixels. Each canvas uses `#000000`, a `#ffffff`
+glyph at 86% of canvas size, and centers the glyph's actual ink bounds. These
+are rendered font glyphs; the browser does not need the font installed.

package/assets/visual-context/browser/manifest.json

@@ -0,0 +1,20 @@
+{
+  "manifest_version": 3,
+  "name": "Sideroom Visual Context",
+  "version": "1.1.0",
+  "description": "Select a page element and attach local source candidates to your Pi session.",
+  "minimum_chrome_version": "116",
+  "permissions": ["activeTab", "scripting", "storage", "alarms"],
+  "icons": { "16": "icons/icon-16.png", "32": "icons/icon-32.png", "48": "icons/icon-48.png", "128": "icons/icon-128.png" },
+  "background": { "service_worker": "background.js" },
+  "commands": {
+    "toggle-inspector": {
+      "suggested_key": "Alt+Shift+S",
+      "description": "Start or stop selecting elements for Pi"
+    }
+  },
+  "action": { "default_popup": "popup.html", "default_title": "Select an element for Pi", "default_icon": { "16": "icons/icon-16.png", "32": "icons/icon-32.png", "48": "icons/icon-48.png" } },
+  "content_security_policy": {
+    "extension_pages": "script-src 'self'; object-src 'self'; connect-src ws://127.0.0.1:* ws://localhost:*"
+  }
+}

package/assets/visual-context/browser/popup.css

@@ -0,0 +1,19 @@
+:root { color-scheme: dark; font-family: "Helvetica Neue", Arial, sans-serif; color: #f2ede3; background: #131211; }
+* { box-sizing: border-box; }
+body { width: 360px; margin: 0; padding: 24px; }
+header { border-top: 2px solid #f2ede3; padding-top: 16px; }
+header img { display: block; }
+details { margin: 16px 0; }
+summary { cursor: pointer; color: #a49d8f; font-size: 13px; }
+h1 { font-size: 30px; line-height: 1.05; letter-spacing: -.035em; margin: 14px 0 18px; }
+.intro, footer { color: #a49d8f; font-size: 13px; line-height: 1.6; }
+label { display: block; margin: 22px 0 8px; font: 11px ui-monospace, monospace; }
+input, select { width: 100%; background: #0b0a09; border: 1px solid #514b42; border-radius: 0; padding: 11px; color: #f2ede3; font: 12px ui-monospace, monospace; }
+button { display: block; width: 100%; border: 1px solid #f2ede3; border-radius: 0; padding: 12px; margin-top: 10px; background: #f2ede3; color: #131211; font: 600 13px "Helvetica Neue", Arial, sans-serif; cursor: pointer; }
+button:hover { background: #fff; }
+button:disabled { opacity: .4; cursor: default; }
+.secondary { background: transparent; border-color: #514b42; color: #a49d8f; }
+.secondary:hover { background: #1b1917; }
+:focus-visible { outline: 2px solid #ffb340; outline-offset: 3px; }
+#status { min-height: 40px; margin: 18px 0; font: 12px/1.6 ui-monospace, monospace; color: #ffb340; overflow-wrap: anywhere; }
+footer { border-top: 1px solid #514b42; margin-top: 22px; padding-top: 14px; font-size: 11px; }

package/assets/visual-context/browser/popup.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Sideroom — Browser context</title>
+    <link rel="stylesheet" href="popup.css" />
+    <script src="popup.js" defer></script>
+  </head>
+  <body>
+    <header><img src="icons/icon-48.png" width="32" height="32" alt="Sideroom" /><h1>Point to the code.</h1></header>
+    <p class="intro">Select an element in this tab. Its source candidates appear in your Pi session.</p>
+    <details id="pairing-details" open><summary>Authorize Windows or WSL</summary><form id="pairing-form">
+      <label for="address">Pair once · address from Pi (F7)</label>
+      <input id="address" type="text" autocomplete="off" spellcheck="false" placeholder="ws://127.0.0.1:…" required />
+      <button id="connect" type="submit">Connect to Pi</button>
+    </form></details>
+    <p id="status" role="status" aria-live="polite">Checking connection…</p>
+    <label for="destination">Send selections to</label>
+    <select id="destination" disabled><option value="">Waiting for Pi…</option></select>
+    <button id="inspect" type="button" disabled>Select an element</button>
+    <p id="shortcut-hint">Escape exits selection. Change the shortcut in your browser's shortcuts page.</p>
+    <button id="disconnect" class="secondary" type="button" disabled>Disconnect</button>
+    <button id="forget" class="secondary" type="button" disabled>Forget authorizations</button>
+    <footer>Click attaches context. Send your instruction in Pi to begin.</footer>
+  </body>
+</html>

package/assets/visual-context/browser/popup.js

@@ -0,0 +1,141 @@
+const form = document.querySelector('#pairing-form');
+const address = document.querySelector('#address');
+const status = document.querySelector('#status');
+const inspect = document.querySelector('#inspect');
+const disconnect = document.querySelector('#disconnect');
+const forget = document.querySelector('#forget');
+const destination = document.querySelector('#destination');
+const connect = document.querySelector('#connect');
+// Edge keeps the Chromium shortcut page under its own scheme; every other
+// Chromium browser the companion supports answers on chrome://.
+const SHORTCUT_PAGE = navigator.userAgent.includes('Edg/')
+  ? 'edge://extensions/shortcuts'
+  : 'chrome://extensions/shortcuts';
+let busy = false;
+let pairingShown = false;
+
+function showStatus(receipt) {
+  status.textContent = receipt.notice ?? receipt.message;
+  if (receipt.connected !== undefined) {
+    inspect.disabled = !receipt.connected || !receipt.selectedId;
+    disconnect.disabled = !receipt.connected;
+  }
+  if (receipt.address !== undefined) {
+    if (!pairingShown) {
+      document.querySelector('#pairing-details').open = !receipt.address;
+      pairingShown = true;
+    }
+    if (document.activeElement !== address) {
+      address.value = receipt.address;
+    }
+    forget.disabled = !receipt.address;
+  }
+  if (receipt.sessions) {
+    destination.replaceChildren();
+    const placeholder = document.createElement('option');
+    placeholder.value = '';
+    placeholder.textContent = receipt.sessions.length
+      ? 'Choose a Pi session…'
+      : 'Waiting for Pi…';
+    destination.append(placeholder);
+    for (const session of receipt.sessions) {
+      const option = document.createElement('option');
+      option.value = session.id;
+      option.textContent = `${session.environment} · ${session.name} · ${session.project}`;
+      destination.append(option);
+    }
+    destination.value = receipt.selectedId;
+    destination.disabled = !receipt.connected || !receipt.sessions.length;
+  }
+}
+
+async function request(message) {
+  const receipt = await chrome.runtime.sendMessage(message);
+  if (!receipt.ok) {
+    throw new Error(receipt.message);
+  }
+  return receipt;
+}
+
+form.addEventListener('submit', async (event) => {
+  event.preventDefault();
+  busy = true;
+  connect.disabled = true;
+  status.textContent = 'Connecting…';
+  try {
+    showStatus(await request({ action: 'connect', address: address.value }));
+  } catch (cause) {
+    showStatus({ message: cause.message, connected: false });
+  } finally {
+    busy = false;
+    connect.disabled = false;
+  }
+});
+
+destination.addEventListener('change', async () => {
+  busy = true;
+  try {
+    showStatus(await request({ action: 'choose', id: destination.value }));
+  } catch (cause) {
+    showStatus({ message: cause.message });
+  } finally {
+    busy = false;
+  }
+});
+
+inspect.addEventListener('click', async () => {
+  try {
+    await request({ action: 'inspect' });
+    window.close();
+  } catch (cause) {
+    showStatus({ message: cause.message });
+  }
+});
+
+for (const button of [disconnect, forget]) {
+  button.addEventListener('click', async () => {
+    busy = true;
+    try {
+      showStatus(
+        await request({ action: button === forget ? 'forget' : 'disconnect' }),
+      );
+      if (button === forget) {
+        address.value = '';
+        document.querySelector('#pairing-details').open = true;
+      }
+    } catch (cause) {
+      showStatus({ message: cause.message });
+    } finally {
+      busy = false;
+    }
+  });
+}
+
+async function refresh() {
+  if (busy) {
+    return;
+  }
+  try {
+    showStatus(await request({ action: 'status' }));
+  } catch (cause) {
+    showStatus({ message: cause.message, connected: false });
+  }
+}
+async function showShortcut() {
+  const hint = document.querySelector('#shortcut-hint');
+  try {
+    const commands = await chrome.commands.getAll();
+    const shortcut = commands.find(
+      (command) => command.name === 'toggle-inspector',
+    )?.shortcut;
+    hint.textContent = shortcut
+      ? `${shortcut} starts or stops selection. Escape also exits. Change it in ${SHORTCUT_PAGE}.`
+      : `No selection shortcut is assigned. Set one in ${SHORTCUT_PAGE}. Escape exits selection.`;
+  } catch (cause) {
+    hint.textContent = `Could not read the shortcut: ${cause.message}. Check ${SHORTCUT_PAGE}.`;
+  }
+}
+void showShortcut();
+void refresh();
+const poll = setInterval(refresh, 1_000);
+window.addEventListener('pagehide', () => clearInterval(poll));

package/extensions/done/guard.ts

@@ -6,6 +6,11 @@ import {
   isToolCallEventType,
   isWriteToolResult,
 } from '@earendil-works/pi-coding-agent';
+import {
+  registerSettleGuard,
+  SETTLE_PRIORITY,
+  withHiddenSteer,
+} from '../shared/settle.ts';
 import { type CheckCommand, commandMatches } from './detect.ts';
 import {
   DONE_GATE_TYPE,
@@ -25,19 +30,22 @@ export type ResolveCommand = (
 
 export type ResolveTestSetup = (ctx: Pick<ExtensionContext, 'cwd'>) => boolean;
 
-export function registerDoneGuard(
-  pi: ExtensionAPI,
-  state: DoneState,
-  resolveCommand: ResolveCommand,
-  resolveTestSetup: ResolveTestSetup,
-): void {
+interface DoneGuardOptions {
+  readonly pi: ExtensionAPI;
+  readonly state: DoneState;
+  readonly resolveCommand: ResolveCommand;
+  readonly resolveTestSetup: ResolveTestSetup;
+}
+
+export function registerDoneGuard({
+  pi,
+  state,
+  resolveCommand,
+  resolveTestSetup,
+}: DoneGuardOptions): void {
   const checkRuns = new Set<string>();
   const mutationPaths = new Map<string, string>();
 
-  pi.on('turn_start', () => {
-    state.steeredThisTurn = false;
-  });
-
   pi.on('tool_call', (event, ctx) => {
     if (
       isToolCallEventType('write', event) ||
@@ -72,41 +80,38 @@ export function registerDoneGuard(
     }
     if (isBashToolResult(event)) {
       const wasCheck = checkRuns.delete(event.toolCallId);
-      if (wasCheck && !event.isError) {
-        state.checksGreen = true;
+      if (wasCheck) {
+        state.checksGreen = !event.isError;
       }
     }
   });
 
-  pi.on('turn_end', (_event, ctx) => {
-    const check = resolveCommand(ctx);
-    if (check !== undefined && shouldSteerDone(state, true)) {
-      state.steeredThisTurn = true;
-      state.steerCount += 1;
-      pi.sendMessage(
-        {
+  registerSettleGuard(pi, {
+    priority: SETTLE_PRIORITY.done,
+    pending: (ctx) =>
+      shouldSteerDone(state, resolveCommand(ctx) !== undefined) ||
+      shouldNoticeMissingTest(state, resolveTestSetup(ctx)),
+    handle: (event, ctx) => {
+      const check = resolveCommand(ctx);
+      if (check !== undefined && shouldSteerDone(state, true)) {
+        state.steerCount += 1;
+        return withHiddenSteer({
+          event,
           customType: DONE_GATE_TYPE,
           content: formatDoneSteer(check.display),
-          display: false,
-        },
-        { triggerTurn: true, deliverAs: 'steer' },
-      );
-      return;
-    }
-
-    if (!shouldNoticeMissingTest(state, resolveTestSetup(ctx))) {
-      return;
-    }
-    state.noticedMissingTest = true;
-    state.steerCount += 1;
-    pi.sendMessage(
-      {
+        });
+      }
+      if (!shouldNoticeMissingTest(state, resolveTestSetup(ctx))) {
+        return;
+      }
+      state.noticedMissingTest = true;
+      state.steerCount += 1;
+      return withHiddenSteer({
+        event,
         customType: MISSING_TEST_NOTICE_TYPE,
         content: formatMissingTestNotice(),
-        display: false,
-      },
-      { triggerTurn: true, deliverAs: 'steer' },
-    );
+      });
+    },
   });
 }
 

package/extensions/done/index.ts

@@ -2,6 +2,7 @@ import type {
   ExtensionAPI,
   ExtensionContext,
 } from '@earendil-works/pi-coding-agent';
+import { startsUserTurn } from '../shared/settle.ts';
 import {
   type CheckCommand,
   detectCheckCommand,
@@ -41,10 +42,10 @@ export default function registerDone(pi: ExtensionAPI): void {
     return hasTests;
   };
 
-  registerDoneGuard(pi, state, resolveCommand, resolveTestSetup);
+  registerDoneGuard({ pi, state, resolveCommand, resolveTestSetup });
 
   pi.on('input', (event) => {
-    if (event.source === 'interactive' || event.source === 'rpc') {
+    if (startsUserTurn(event)) {
       resetDoneRun(state);
     }
   });

package/extensions/done/model.ts

@@ -1,7 +1,6 @@
 export interface DoneState {
   mutated: boolean;
   checksGreen: boolean;
-  steeredThisTurn: boolean;
   steerCount: number;
   mutatedSource: boolean;
   mutatedTest: boolean;
@@ -27,7 +26,6 @@ export function createDoneState(): DoneState {
   return {
     mutated: false,
     checksGreen: false,
-    steeredThisTurn: false,
     steerCount: 0,
     mutatedSource: false,
     mutatedTest: false,
@@ -38,7 +36,6 @@ export function createDoneState(): DoneState {
 export function resetDoneRun(state: DoneState): void {
   state.mutated = false;
   state.checksGreen = false;
-  state.steeredThisTurn = false;
   state.steerCount = 0;
   state.mutatedSource = false;
   state.mutatedTest = false;
@@ -63,7 +60,6 @@ export function shouldSteerDone(
     hasCommand &&
     state.mutated &&
     !state.checksGreen &&
-    !state.steeredThisTurn &&
     state.steerCount < MAX_DONE_STEERS
   );
 }
@@ -86,5 +82,5 @@ export function formatDoneSteer(display: string): string {
 }
 
 export function formatMissingTestNotice(): string {
-  return 'This run changed code files and no test file. Add or update the test that covers the change before finishing.';
+  return 'This run changed code files and no test file. Check whether existing tests cover the changed behavior; add or update a test if coverage is missing, then rerun the relevant checks before finishing.';
 }

package/extensions/explain/guard.ts

@@ -4,7 +4,8 @@ import {
   isWriteToolResult,
 } from '@earendil-works/pi-coding-agent';
 import {
-  acceptsSettleSteer,
+  registerSettleGuard,
+  SETTLE_PRIORITY,
   startsUserTurn,
   withHiddenSteer,
 } from '../shared/settle.ts';
@@ -54,15 +55,16 @@ export function registerExplainGuard(
   // agent_before_settle runs after retries and compaction recovery, so the
   // walkthrough is never offered over reworked work, and its continuation
   // stays inside the same run instead of starting a second one.
-  pi.on('agent_before_settle', (event, ctx) => {
-    if (!acceptsSettleSteer(event)) {
-      return;
-    }
-    const decision = decideOffer(state, ctx.mode);
-    applyOfferDecision(state, decision);
-    if (decision !== EXPLAIN_DECISION.send) {
-      return;
-    }
-    return withHiddenSteer(event, EXPLAIN_OFFER_TYPE, EXPLAIN_OFFER);
+  registerSettleGuard(pi, {
+    priority: SETTLE_PRIORITY.explain,
+    pending: (ctx) => decideOffer(state, ctx.mode) === EXPLAIN_DECISION.send,
+    handle: (event, ctx) => {
+      applyOfferDecision(state, decideOffer(state, ctx.mode));
+      return withHiddenSteer({
+        event,
+        customType: EXPLAIN_OFFER_TYPE,
+        content: EXPLAIN_OFFER,
+      });
+    },
   });
 }