@rmrdeveloper/sideroom-pi 8.12.0 → 8.13.0

package/extensions/visual-context/broker.ts

@@ -0,0 +1,292 @@
+import { randomUUID, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { Check } from 'typebox/value';
+import { type WebSocket, WebSocketServer } from 'ws';
+import { parseEnvelope, send } from './envelope.ts';
+import {
+  BRIDGE_PATH,
+  MAX_MESSAGE_BYTES,
+  MESSAGE_TYPE,
+  PEER_ROLE,
+  PI_ORIGIN,
+  PROTOCOL_VERSION,
+  parseSelection,
+  type SessionDescriptor,
+  SessionDescriptorSchema,
+} from './model.ts';
+import type { PairingIdentity } from './pairing.ts';
+
+const MAX_PEERS = 20;
+const REQUEST_TIMEOUT_MS = 10_000;
+const MIN_SELECTION_INTERVAL_MS = 300;
+const EXTENSION_ORIGIN = /^chrome-extension:\/\/[a-p]{32}$/u;
+interface Peer {
+  role?: string;
+  session?: SessionDescriptor;
+  lastSelectionAt: number;
+}
+interface Delivery {
+  browser: WebSocket;
+  pi: WebSocket;
+  id: string;
+  revision: string;
+  timer: NodeJS.Timeout;
+}
+export interface LocalBroker {
+  close(): Promise<void>;
+}
+
+export async function startBroker({
+  identity,
+  onError,
+}: {
+  readonly identity: PairingIdentity;
+  readonly onError: (error: Error) => void;
+}): Promise<LocalBroker> {
+  const server = createServer((_request, response) => {
+    response.writeHead(404, { 'Cache-Control': 'no-store' });
+    response.end();
+  });
+  const sockets = new WebSocketServer({
+    noServer: true,
+    maxPayload: MAX_MESSAGE_BYTES,
+  });
+  const peers = new Map<WebSocket, Peer>();
+  const deliveries = new Map<string, Delivery>();
+  const sessions = () =>
+    [...peers.values()].flatMap((peer) => (peer.session ? [peer.session] : []));
+  const publish = () => {
+    for (const [socket, peer] of peers) {
+      if (peer.role === PEER_ROLE.browser) {
+        send(socket, { type: MESSAGE_TYPE.sessions, sessions: sessions() });
+      }
+    }
+  };
+  server.on('upgrade', (request, socket, head) => {
+    const origin = request.headers.origin;
+    if (
+      request.url !== BRIDGE_PATH ||
+      typeof origin !== 'string' ||
+      (origin !== PI_ORIGIN && !EXTENSION_ORIGIN.test(origin)) ||
+      peers.size >= MAX_PEERS
+    ) {
+      socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
+      return;
+    }
+    sockets.handleUpgrade(request, socket, head, (connection) =>
+      sockets.emit('connection', connection, origin),
+    );
+  });
+  sockets.on('connection', (socket: WebSocket, origin: string) => {
+    const peer: Peer = { lastSelectionAt: 0 };
+    peers.set(socket, peer);
+    const authenticationTimeout = setTimeout(
+      () => socket.terminate(),
+      REQUEST_TIMEOUT_MS,
+    );
+    authenticationTimeout.unref();
+    socket.on('error', onError);
+    socket.on('close', () => {
+      clearTimeout(authenticationTimeout);
+      peers.delete(socket);
+      for (const [requestId, delivery] of deliveries) {
+        if (delivery.pi === socket || delivery.browser === socket) {
+          clearTimeout(delivery.timer);
+          deliveries.delete(requestId);
+          if (delivery.browser !== socket) {
+            send(delivery.browser, {
+              type: MESSAGE_TYPE.error,
+              id: delivery.id,
+              message:
+                'The destination session disconnected. Select the element again.',
+            });
+          }
+        }
+      }
+      publish();
+    });
+    socket.on('message', (bytes, binary) => {
+      try {
+        const message = parseEnvelope(bytes.toString(), binary);
+        if (!peer.role) {
+          const expectedRole =
+            origin === PI_ORIGIN ? PEER_ROLE.pi : PEER_ROLE.browser;
+          if (
+            message.type !== MESSAGE_TYPE.authenticate ||
+            message.version !== PROTOCOL_VERSION ||
+            message.role !== expectedRole ||
+            !matchesSecret(message.token, identity.token)
+          ) {
+            socket.close(1008, 'Invalid pairing');
+            return;
+          }
+          peer.role = expectedRole;
+          clearTimeout(authenticationTimeout);
+          send(socket, {
+            type: MESSAGE_TYPE.ready,
+            version: PROTOCOL_VERSION,
+            sessions: sessions(),
+          });
+          return;
+        }
+        if (message.type === MESSAGE_TYPE.ping) {
+          send(socket, { type: MESSAGE_TYPE.pong });
+          return;
+        }
+        if (peer.role === PEER_ROLE.pi) {
+          if (
+            message.type === MESSAGE_TYPE.register &&
+            Check(SessionDescriptorSchema, message.session)
+          ) {
+            const registeredSession = message.session;
+            if (peer.session && peer.session.id !== registeredSession.id) {
+              throw new Error(
+                'A Pi connection cannot replace another instance.',
+              );
+            }
+            if (
+              [...peers.values()].some(
+                (other) =>
+                  other !== peer && other.session?.id === registeredSession.id,
+              )
+            ) {
+              throw new Error('The Pi instance is already registered.');
+            }
+            peer.session = registeredSession;
+            send(socket, {
+              type: MESSAGE_TYPE.register,
+              revision: peer.session.revision,
+            });
+            publish();
+            return;
+          }
+          if (
+            message.type === MESSAGE_TYPE.result &&
+            typeof message.requestId === 'string'
+          ) {
+            const delivery = deliveries.get(message.requestId);
+            if (!delivery || delivery.pi !== socket) {
+              throw new Error('Unknown selection receipt.');
+            }
+            clearTimeout(delivery.timer);
+            deliveries.delete(message.requestId);
+            const stale = peer.session?.revision !== delivery.revision;
+            send(
+              delivery.browser,
+              typeof message.error === 'string' || stale
+                ? {
+                    type: MESSAGE_TYPE.error,
+                    id: delivery.id,
+                    message: stale
+                      ? 'The session changed. Select the element again.'
+                      : String(message.error).slice(0, 500),
+                  }
+                : {
+                    type: MESSAGE_TYPE.received,
+                    id: delivery.id,
+                    candidates: message.candidates,
+                  },
+            );
+            return;
+          }
+          throw new Error('Invalid Pi message.');
+        }
+        if (
+          message.type !== MESSAGE_TYPE.selection ||
+          !Check(SessionDescriptorSchema, message.target)
+        ) {
+          throw new Error(
+            'Choose a destination session in the browser companion.',
+          );
+        }
+        const target = message.target;
+        const destination = [...peers.entries()].find(
+          ([, entry]) =>
+            entry.session?.id === target.id &&
+            entry.session.revision === target.revision,
+        );
+        if (!destination) {
+          throw new Error(
+            'The destination session changed. Select the element again.',
+          );
+        }
+        if (
+          Date.now() - peer.lastSelectionAt < MIN_SELECTION_INTERVAL_MS ||
+          deliveries.size >= 128
+        ) {
+          throw new Error(
+            'Pi is still processing selections. Try again shortly.',
+          );
+        }
+        const selection = parseSelection(message.selection);
+        peer.lastSelectionAt = Date.now();
+        const requestId = randomUUID();
+        const timer = setTimeout(() => {
+          deliveries.delete(requestId);
+          send(socket, {
+            type: MESSAGE_TYPE.error,
+            id: selection.id,
+            message:
+              'The destination session did not respond. Select the element again.',
+          });
+        }, REQUEST_TIMEOUT_MS);
+        timer.unref();
+        deliveries.set(requestId, {
+          browser: socket,
+          pi: destination[0],
+          id: selection.id,
+          revision: target.revision,
+          timer,
+        });
+        send(destination[0], {
+          type: MESSAGE_TYPE.deliver,
+          requestId,
+          revision: target.revision,
+          selection,
+        });
+      } catch (cause) {
+        const error =
+          cause instanceof Error
+            ? cause
+            : new Error('Cannot route browser selection.', { cause });
+        send(socket, { type: MESSAGE_TYPE.error, message: error.message });
+        if (!peer.role) {
+          socket.close(1008, 'Invalid pairing');
+        }
+      }
+    });
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(identity.port, '127.0.0.1', () => {
+      server.removeListener('error', reject);
+      resolve();
+    });
+  });
+  server.on('error', onError);
+  let closing: Promise<void> | undefined;
+  return {
+    close() {
+      closing ??= new Promise<void>((resolve, reject) => {
+        for (const delivery of deliveries.values()) {
+          clearTimeout(delivery.timer);
+        }
+        deliveries.clear();
+        for (const socket of sockets.clients) {
+          socket.terminate();
+        }
+        sockets.close();
+        server.close((error) => (error ? reject(error) : resolve()));
+      });
+      return closing;
+    },
+  };
+}
+
+function matchesSecret(token: unknown, secret: string): boolean {
+  return (
+    typeof token === 'string' &&
+    /^[a-f0-9]{64}$/u.test(token) &&
+    timingSafeEqual(Buffer.from(token), Buffer.from(secret))
+  );
+}

package/extensions/visual-context/envelope.ts

@@ -0,0 +1,34 @@
+import { WebSocket } from 'ws';
+
+const INVALID_MESSAGE = 'Invalid inspector message.';
+
+export function send(
+  socket: WebSocket,
+  message: Readonly<Record<string, unknown>>,
+): void {
+  if (socket.readyState === WebSocket.OPEN) {
+    socket.send(JSON.stringify(message));
+  }
+}
+
+export function parseEnvelope(
+  source: string,
+  binary = false,
+): Record<string, unknown> {
+  let message: unknown;
+  try {
+    message = JSON.parse(source);
+  } catch (cause) {
+    throw new Error(INVALID_MESSAGE, { cause });
+  }
+  if (
+    binary ||
+    !message ||
+    typeof message !== 'object' ||
+    Array.isArray(message) ||
+    !('type' in message)
+  ) {
+    throw new Error(INVALID_MESSAGE);
+  }
+  return message as Record<string, unknown>;
+}

package/extensions/visual-context/index.ts

@@ -0,0 +1,328 @@
+import { randomUUID } from 'node:crypto';
+import {
+  type ExtensionAPI,
+  type ExtensionContext,
+  getAgentDir,
+} from '@earendil-works/pi-coding-agent';
+import { connectSession, type VisualBridge } from './bridge.ts';
+import {
+  candidateLabel,
+  cleanLabel,
+  elementLabel,
+  type PendingSelection,
+  type SessionDescriptor,
+  VISUAL_SHORTCUT,
+  VISUAL_WIDGET,
+} from './model.ts';
+import { ensurePairing, pairingAddress, readPairing } from './pairing.ts';
+import {
+  commitPending,
+  createVisualStore,
+  prepareContext,
+  receiveSelection,
+  restorePending,
+} from './session.ts';
+import { candidateIsCurrent } from './source.ts';
+import { BROWSER_EXTENSION_DIRECTORY, refreshVisualWidget } from './ui.ts';
+
+const CONTROL = {
+  pair: 'Pair browser',
+  stop: 'Disconnect browser',
+  clear: 'Remove all pending elements',
+} as const;
+
+type VisualDialogOption =
+  | { readonly label: string; readonly action: 'pair' }
+  | { readonly label: string; readonly action: 'stop' }
+  | { readonly label: string; readonly action: 'clear' }
+  | {
+      readonly label: string;
+      readonly action: 'review';
+      readonly entry: PendingSelection;
+    };
+
+function notifyRestoreFailure(ctx: ExtensionContext, cause: unknown): void {
+  ctx.ui.notify(`Cannot restore browser context: ${String(cause)}`, 'error');
+}
+
+export default function registerVisualContext(
+  pi: ExtensionAPI,
+  agentDirectory = getAgentDir(),
+): void {
+  const store = createVisualStore();
+  let bridge: VisualBridge | undefined;
+  let activeContext: ExtensionContext | undefined;
+  let opening = false;
+  let generation = 0;
+  let preparedContext: ReturnType<typeof prepareContext>;
+  const instanceId = randomUUID();
+  let destination: SessionDescriptor | undefined;
+
+  async function stopBridge(): Promise<void> {
+    generation += 1;
+    preparedContext = undefined;
+    const previous = bridge;
+    bridge = undefined;
+    await previous?.close();
+  }
+
+  const refresh = (ctx: ExtensionContext): void =>
+    refreshVisualWidget(store.pending, ctx);
+  const savePending = (
+    ctx: ExtensionContext,
+    pending: readonly PendingSelection[],
+  ): void => {
+    commitPending({ store, pi, pending });
+    refresh(ctx);
+  };
+  // An async dialog may only act while it still belongs to the active session.
+  const dialogIsCurrent = (ctx: ExtensionContext, epoch: number): boolean =>
+    epoch === generation && activeContext === ctx;
+  async function activate(ctx: ExtensionContext): Promise<void> {
+    generation += 1;
+    preparedContext = undefined;
+    activeContext = ctx;
+    if (ctx.mode !== 'tui') {
+      await stopBridge();
+      return;
+    }
+    destination = {
+      id: instanceId,
+      revision: randomUUID(),
+      name: cleanLabel(
+        ctx.sessionManager.getSessionName() ??
+          ctx.sessionManager.getSessionId(),
+        160,
+      ),
+      project: cleanLabel(ctx.cwd, 512),
+      environment:
+        process.platform === 'win32'
+          ? 'Windows'
+          : process.env.WSL_DISTRO_NAME
+            ? `WSL (${cleanLabel(process.env.WSL_DISTRO_NAME, 140)})`
+            : process.platform,
+    };
+    restorePending({ store, ctx });
+    refresh(ctx);
+    if (!ctx.isProjectTrusted()) {
+      await stopBridge();
+      return;
+    }
+    bridge?.update(destination);
+    if (!bridge) {
+      const identity = readPairing(agentDirectory);
+      if (identity) {
+        await openBridge(identity);
+      }
+    }
+  }
+  async function openBridge(
+    identity: Awaited<ReturnType<typeof ensurePairing>>,
+  ): Promise<void> {
+    if (!destination) {
+      throw new Error('The Pi conversation is not available.');
+    }
+    const captured = generation;
+    const created = await connectSession({
+      identity,
+      session: destination,
+      onSelection: (selection, revision) => {
+        const current = activeContext;
+        if (
+          !current?.isProjectTrusted() ||
+          destination?.revision !== revision
+        ) {
+          throw new Error('The destination Pi session is no longer trusted.');
+        }
+        const receipt = receiveSelection({
+          store,
+          pi,
+          cwd: current.cwd,
+          selection,
+        });
+        refresh(current);
+        return receipt;
+      },
+      onError: (error) => activeContext?.ui.notify(error.message, 'error'),
+    });
+    const current = activeContext;
+    if (!current || !dialogIsCurrent(current, captured)) {
+      await created.close();
+      return;
+    }
+    bridge = created;
+  }
+  const activateSafely = async (ctx: ExtensionContext): Promise<void> => {
+    try {
+      await activate(ctx);
+    } catch (cause) {
+      notifyRestoreFailure(ctx, cause);
+    }
+  };
+  pi.on('session_start', (_event, ctx) => activateSafely(ctx));
+  pi.on('session_tree', (_event, ctx) => activateSafely(ctx));
+  pi.on('session_compact', (_event, ctx) => {
+    activeContext = ctx;
+    try {
+      restorePending({ store, ctx });
+    } catch (cause) {
+      notifyRestoreFailure(ctx, cause);
+    }
+    refresh(ctx);
+  });
+  pi.on('session_shutdown', async (_event, ctx) => {
+    activeContext = undefined;
+    await stopBridge();
+    ctx.ui.setWidget(VISUAL_WIDGET, undefined);
+  });
+  pi.on('input', (event, ctx) => {
+    if (
+      event.source !== 'interactive' ||
+      !ctx.isIdle() ||
+      event.streamingBehavior !== undefined ||
+      /^[!/]/u.test(event.text.trimStart())
+    ) {
+      return;
+    }
+    const context = prepareContext({ store, cwd: ctx.cwd });
+    if (context === undefined) {
+      return;
+    }
+    preparedContext = context;
+    return {
+      action: 'transform',
+      text: `${event.text}\n\n${context.text}`,
+      images: event.images,
+    };
+  });
+  // Input precedes model/auth validation in Pi. Keep the pending snapshot until
+  // the run actually starts so a failed submission cannot lose the attachment.
+  pi.on('before_agent_start', (event, ctx) => {
+    const attachment = preparedContext;
+    preparedContext = undefined;
+    if (!attachment || !event.prompt.includes(attachment.text)) {
+      return;
+    }
+    savePending(
+      ctx,
+      store.pending.filter(
+        (entry) => !attachment.selectionIds.includes(entry.selection.id),
+      ),
+    );
+  });
+  pi.registerShortcut(VISUAL_SHORTCUT, {
+    description: 'Pair the browser or review selected elements',
+    handler: async (ctx) => {
+      if (opening || ctx.mode !== 'tui') {
+        return;
+      }
+      if (!ctx.isProjectTrusted()) {
+        ctx.ui.notify(
+          'Trust this project in Pi before connecting the browser.',
+          'warning',
+        );
+        return;
+      }
+      opening = true;
+      try {
+        if (!destination || activeContext !== ctx) {
+          await activate(ctx);
+        }
+        const dialogGeneration = generation;
+        const stopOptions: readonly VisualDialogOption[] = bridge
+          ? [{ label: CONTROL.stop, action: 'stop' }]
+          : [];
+        const options: readonly VisualDialogOption[] = [
+          { label: CONTROL.pair, action: 'pair' },
+          ...store.pending.map(
+            (entry): VisualDialogOption => ({
+              label: `Review ${elementLabel(entry.selection)} [${entry.selection.id}]`,
+              action: 'review',
+              entry,
+            }),
+          ),
+          { label: CONTROL.clear, action: 'clear' },
+          ...stopOptions,
+        ];
+        const choice = await ctx.ui.select(
+          'Browser context',
+          options.map((option) => option.label),
+        );
+        if (!dialogIsCurrent(ctx, dialogGeneration)) {
+          return;
+        }
+        const picked = options.find((option) => option.label === choice);
+        if (!picked) {
+          return;
+        }
+        if (picked.action === 'pair') {
+          const identity = await ensurePairing(agentDirectory);
+          if (!bridge) {
+            await openBridge(identity);
+          }
+          if (!dialogIsCurrent(ctx, dialogGeneration)) {
+            return;
+          }
+          ctx.ui.notify(
+            `Load the browser extension from ${BROWSER_EXTENSION_DIRECTORY}. Pair once with this address: ${pairingAddress(identity)}. The browser reconnects to future sessions automatically.`,
+            'info',
+          );
+          await ctx.ui.editor(
+            'Pairing address — copy into the Sideroom browser extension',
+            pairingAddress(identity),
+          );
+          return;
+        }
+        if (picked.action === 'stop') {
+          await stopBridge();
+          ctx.ui.notify(
+            'This session stopped receiving browser elements. Other Pi instances remain available. Pending elements are preserved.',
+            'info',
+          );
+          return;
+        }
+        if (picked.action === 'clear') {
+          savePending(ctx, []);
+          return;
+        }
+        const entry = picked.entry;
+        const labels = entry.resolution.candidates.map(
+          (candidate) =>
+            `${candidateLabel(candidate)} · ${candidate.reasons.join(', ')}`,
+        );
+        const remove = 'Remove this element';
+        const selected = await ctx.ui.select(
+          'Choose a source candidate — origin is inferred',
+          [...labels, remove],
+        );
+        if (!dialogIsCurrent(ctx, dialogGeneration)) {
+          return;
+        }
+        if (selected === undefined) {
+          return;
+        }
+        const candidate = entry.resolution.candidates[labels.indexOf(selected)];
+        if (candidate && !candidateIsCurrent(ctx.cwd, candidate)) {
+          ctx.ui.notify(
+            'The source changed. Select the element again in your browser.',
+            'warning',
+          );
+          return;
+        }
+        const pending =
+          selected === remove
+            ? store.pending.filter(
+                (item) => item.selection.id !== entry.selection.id,
+              )
+            : store.pending.map((item) =>
+                item.selection.id === entry.selection.id
+                  ? { ...item, chosen: candidate }
+                  : item,
+              );
+        savePending(ctx, pending);
+      } finally {
+        opening = false;
+      }
+    },
+  });
+}

package/extensions/visual-context/literal.ts

@@ -0,0 +1,34 @@
+import { parseExpression } from '@babel/parser';
+
+const SYNTAX_ERROR_CODES = new Set([
+  'BABEL_PARSER_SYNTAX_ERROR',
+  'BABEL_PARSER_SOURCETYPE_MODULE_REQUIRED',
+]);
+
+export function isBabelSyntaxError(cause: unknown): boolean {
+  return (
+    cause instanceof Error &&
+    'code' in cause &&
+    SYNTAX_ERROR_CODES.has(String(cause.code))
+  );
+}
+
+// Only syntax literals are read. No inspected source is imported or executed.
+export function literalText(expression: string): string | undefined {
+  let node: ReturnType<typeof parseExpression>;
+  try {
+    node = parseExpression(expression, { plugins: ['typescript'] });
+  } catch (cause) {
+    if (isBabelSyntaxError(cause)) {
+      return undefined;
+    }
+    throw new Error('Cannot parse a source expression', { cause });
+  }
+  if (node.type === 'StringLiteral') {
+    return node.value;
+  }
+  if (node.type === 'TemplateLiteral' && node.expressions.length === 0) {
+    return node.quasis[0]?.value.cooked ?? undefined;
+  }
+  return undefined;
+}