@rmrdeveloper/sideroom-pi 8.11.0 → 8.13.0

package/extensions/jev/workflow.ts

@@ -0,0 +1,188 @@
+import { type AskParams, parseAskParams } from '../ask/model.ts';
+import {
+  parseTodoParams,
+  TODO_STATUS,
+  type TodoItem,
+  type TodoToolParameters,
+} from '../todo/model.ts';
+import {
+  JEV_MODEL,
+  type JevFileState,
+  type JevNoulQuestion,
+  type JevRequestBody,
+  requestFitsBudget,
+} from './model.ts';
+
+const MAX_EVIDENCE_FILES = 4;
+
+type ChangedFileEvidence = Pick<JevFileState, 'file' | 'change'>;
+
+export interface WorkflowEvidence {
+  readonly files: Map<string, ChangedFileEvidence>;
+  readonly completed: Map<string, string>;
+  partial: boolean;
+  checks: 'unknown' | 'passed' | 'failed' | 'stale';
+}
+
+export function createWorkflowEvidence(): WorkflowEvidence {
+  return {
+    files: new Map(),
+    completed: new Map(),
+    partial: false,
+    checks: 'unknown',
+  };
+}
+
+export function resetWorkflowEvidence(evidence: WorkflowEvidence): void {
+  evidence.files.clear();
+  evidence.completed.clear();
+  evidence.partial = false;
+  evidence.checks = 'unknown';
+}
+
+export function recordFileEvidence(
+  evidence: WorkflowEvidence,
+  file: JevFileState,
+): void {
+  evidence.checks = 'stale';
+  evidence.files.delete(file.file.path);
+  evidence.files.set(file.file.path, { file: file.file, change: file.change });
+  if (evidence.files.size > MAX_EVIDENCE_FILES) {
+    const oldest = evidence.files.keys().next().value;
+    if (oldest !== undefined) {
+      evidence.files.delete(oldest);
+    }
+    evidence.partial = true;
+  }
+}
+
+function question(instructions: string, violation: string): JevNoulQuestion {
+  return {
+    type: 'noul',
+    instructions,
+    criteria: {
+      true: violation,
+      false:
+        'No concrete contradiction is visible, or the supplied evidence is insufficient',
+    },
+  };
+}
+
+export function buildAskReview(input: unknown): JevRequestBody | undefined {
+  const parsed = parseAskParams(input as AskParams);
+  if (!parsed.ok) {
+    return undefined;
+  }
+  const request: JevRequestBody = {
+    model: JEV_MODEL,
+    state: { kind: 'questionnaire', questions: parsed.questions },
+    questions: {
+      'question-options': question(
+        'Do the supplied questions contain overlapping single-selection options or bundle independent decisions so no option can express a reasonable combination? Multiple selections may intentionally overlap. Judge only the question text, not unseen requirements.',
+        'The wording visibly prevents a clear independent choice',
+      ),
+      'question-recommendation': question(
+        'Does a recommended option claim factual certainty or decisive cost/performance figures without support in the supplied question, or contradict its stated constraints? A preference alone need not include proof. Do not assume unseen project evidence is absent; flag only a demonstrably unsupported assertion or contradiction in the wording.',
+        'The recommendation visibly contradicts stated constraints or asserts an unsupported decisive fact',
+      ),
+    },
+  };
+  return requestFitsBudget(request) ? request : undefined;
+}
+
+export function completedItems(
+  details: unknown,
+): readonly TodoItem[] | undefined {
+  if (typeof details !== 'object' || details === null || 'error' in details) {
+    return undefined;
+  }
+  const parsed = parseTodoParams({
+    action: 'propose',
+    items: 'items' in details ? details.items : undefined,
+  } as TodoToolParameters);
+  if (!parsed.ok || parsed.params.action !== 'propose') {
+    return undefined;
+  }
+  return parsed.params.items.filter(
+    (item) => item.status === TODO_STATUS.completed,
+  );
+}
+
+export function buildBoardReview({
+  items,
+  evidence,
+  changedIds,
+}: {
+  readonly items: readonly TodoItem[];
+  readonly evidence: WorkflowEvidence;
+  readonly changedIds?: ReadonlySet<string>;
+}): JevRequestBody | undefined {
+  const newlyCompleted = items.filter(
+    (item) =>
+      (changedIds === undefined || changedIds.has(item.id)) &&
+      evidence.completed.get(item.id) !== item.content,
+  );
+  evidence.completed.clear();
+  for (const item of items) {
+    evidence.completed.set(item.id, item.content);
+  }
+  if (
+    newlyCompleted.length === 0 ||
+    (evidence.files.size === 0 &&
+      evidence.checks !== 'passed' &&
+      evidence.checks !== 'failed')
+  ) {
+    return undefined;
+  }
+  const files: ChangedFileEvidence[] = [];
+  const state = {
+    kind: 'completion',
+    items: newlyCompleted,
+    evidence: { files, checks: evidence.checks, partial: evidence.partial },
+  };
+  const request: JevRequestBody = {
+    model: JEV_MODEL,
+    state,
+    questions: {
+      'board-completion': question(
+        'Do the newly completed tasks make a concrete claim contradicted by the supplied code changes or check status? Check status concerns only the detected project check in this user turn and becomes stale after a mutation. Missing evidence, unknown/stale checks and partial files do not prove unfinished work. Do not require every task to involve code or tests. Flag only an explicit mismatch, such as claiming checks passed when the observed latest checks failed.',
+        'A completed task claims behavior or a check result demonstrably contradicted by visible evidence',
+      ),
+    },
+  };
+  for (const file of evidence.files.values()) {
+    files.push(file);
+    if (!requestFitsBudget(request)) {
+      files.pop();
+      state.evidence.partial = true;
+    }
+  }
+  return (files.length > 0 ||
+    evidence.checks === 'passed' ||
+    evidence.checks === 'failed') &&
+    requestFitsBudget(request)
+    ? request
+    : undefined;
+}
+
+export function completionIds(input: unknown): ReadonlySet<string> {
+  const parsed = parseTodoParams(input as TodoToolParameters);
+  if (!parsed.ok) {
+    return new Set();
+  }
+  if (parsed.params.action === 'propose') {
+    return new Set(
+      parsed.params.items
+        .filter((item) => item.status === TODO_STATUS.completed)
+        .map((item) => item.id),
+    );
+  }
+  return new Set(
+    parsed.params.patches
+      .filter(
+        (patch) =>
+          patch.status === TODO_STATUS.completed || patch.content !== undefined,
+      )
+      .map((patch) => patch.id),
+  );
+}

package/extensions/persona/execute.ts

@@ -1,8 +1,6 @@
-import {
-  formatPersonaDetail,
-  type PersonaToolDetails,
-  personaToolDetails,
-} from './model.ts';
+import { readFileSync } from 'node:fs';
+import { PERSONA_SKILL_PATH } from './catalog.ts';
+import { type PersonaToolDetails, personaToolDetails } from './model.ts';
 
 export interface PersonaToolResult {
   readonly content: { readonly type: 'text'; readonly text: string }[];
@@ -11,7 +9,7 @@ export interface PersonaToolResult {
 
 export function executePersona(): PersonaToolResult {
   return {
-    content: [{ type: 'text', text: formatPersonaDetail() }],
+    content: [{ type: 'text', text: readFileSync(PERSONA_SKILL_PATH, 'utf8') }],
     details: personaToolDetails(),
   };
 }

package/extensions/persona/index.ts

@@ -15,9 +15,10 @@ import { personaStatusLabel } from './model.ts';
 import { appendPersonaReminder } from './prompt.ts';
 
 export const PERSONA_DESCRIPTION =
-  "Read Sideroom's voice rules and hard prohibitions for user-facing answers.";
+  'Load the complete Sideroom writing guide before a substantial explanation, findings report, implementation summary, or user-facing documentation; also use when asked for clearer, shorter, or less technical wording. Reuse while in context.';
 
-export const PERSONA_PROMPT_SNIPPET = 'Read the active Sideroom persona.';
+export const PERSONA_PROMPT_SNIPPET =
+  'Load the complete writing guide before substantial user-facing prose.';
 
 // Pi loads extensions/*/index.ts through export default.
 export default function registerPersona(pi: ExtensionAPI): void {

package/extensions/persona/model.ts

@@ -1,11 +1,4 @@
-import {
-  PERSONA_SKILL_PATH,
-  PERSONA_TOOL_NAME,
-  PROHIBITIONS,
-  type Prohibition,
-  TEXT_SCOPE,
-  VOICE_RULES,
-} from './catalog.ts';
+import { PERSONA_TOOL_NAME, PROHIBITIONS, VOICE_RULES } from './catalog.ts';
 import type { ProhibitionViolation } from './checks.ts';
 
 // Pi narrows these blocks before handing the message over; the shape is
@@ -45,22 +38,6 @@ export function personaToolDetails(): PersonaToolDetails {
   };
 }
 
-export function formatPersonaDetail(): string {
-  return [
-    'Sideroom persona: one always-on voice; no profiles or switching.',
-    '',
-    'Voice rules',
-    ...VOICE_RULES.map((rule) => `- ${rule.instruction}`),
-    '',
-    'Hard prohibitions',
-    ...PROHIBITIONS.map(
-      (prohibition) => `- ${prohibition.rule} (${enforcementOf(prohibition)})`,
-    ),
-    '',
-    `Complete guide: ${PERSONA_SKILL_PATH}`,
-  ].join('\n');
-}
-
 export function formatBlockReason(
   path: string,
   violations: readonly ProhibitionViolation[],
@@ -112,10 +89,3 @@ export function assistantMessageText(content: readonly TextBlock[]): string {
   }
   return parts.join('\n');
 }
-
-function enforcementOf(prohibition: Prohibition): string {
-  if (prohibition.scopes.includes(TEXT_SCOPE.artifact)) {
-    return 'blocked on write and edit';
-  }
-  return 'corrected with a steer';
-}

package/extensions/persona/prompt.ts

@@ -23,12 +23,14 @@ export const PERSONA_EXAMPLES = [
 ] as const;
 
 export const PERSONA_REMINDER = `${PERSONA_REMINDER_HEADING}
+Apply this voice to progress messages, final answers, and user-facing documentation.
 Voice: ${VOICE_SUMMARY}
 Never: ${PROHIBITION_SUMMARY}
 ${ENFORCEMENT_SUMMARY}
 Examples:
 ${PERSONA_EXAMPLES.join('\n')}
-Full guide: call ${PERSONA_TOOL_NAME} or read ${PERSONA_SKILL_PATH}.`;
+Before the first substantial explanation or report, call ${PERSONA_TOOL_NAME} or read ${PERSONA_SKILL_PATH}; reuse the complete guide while it remains in context.
+Before sending prose, check: outcome first, necessary terms explained, no repetition or invented labels. Preserve evidence and requested detail.`;
 
 export function appendPersonaReminder(systemPrompt: string): string {
   if (systemPrompt.includes(PERSONA_REMINDER_HEADING)) {

package/extensions/shared/settle.ts

@@ -1,13 +1,31 @@
 import type {
   AgentBeforeSettleEvent,
   AgentBeforeSettleEventResult,
+  ExtensionAPI,
+  ExtensionContext,
   InputEvent,
   InputSource,
 } from '@earendil-works/pi-coding-agent';
 
 const COMPLETED_OUTCOME = 'completed';
-const USER_ROLE = 'user';
 const CUSTOM_MESSAGE_ENTRY = 'custom_message';
+const SETTLE_PRIORITY_EVENT = 'sideroom:settle-priority';
+
+export const SETTLE_PRIORITY = { review: 0, done: 1, explain: 2 } as const;
+
+interface SettlePriorityRequest {
+  readonly ctx: ExtensionContext;
+  readonly priorities: Set<number>;
+}
+
+interface SettleGuard {
+  readonly priority: number;
+  readonly pending: (ctx: ExtensionContext) => boolean;
+  readonly handle: (
+    event: AgentBeforeSettleEvent,
+    ctx: ExtensionContext,
+  ) => AgentBeforeSettleEventResult | undefined;
+}
 const USER_INPUT_SOURCES: ReadonlySet<InputSource> = new Set([
   'interactive',
   'rpc',
@@ -22,24 +40,56 @@ export function startsUserTurn(event: InputEvent): boolean {
   );
 }
 
-// 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.
+// Any queued message or an earlier handler's continuation still has work to
+// run. Yield without consuming the guard's state until a quiet boundary.
 export function acceptsSettleSteer(event: AgentBeforeSettleEvent): boolean {
-  if (event.outcome !== COMPLETED_OUTCOME) {
-    return false;
-  }
-  return !event.context.pendingMessages.some(
-    (message) => message.role === USER_ROLE,
+  return (
+    event.outcome === COMPLETED_OUTCOME &&
+    !event.continue &&
+    event.context.pendingMessages.length === 0
   );
 }
 
+// Pi gives each extension its own API object. Its synchronous event bus is
+// shared, so ask which stages are pending rather than relying on load order
+// or module-global state that would leak across sessions and reloads.
+export function registerSettleGuard(
+  pi: ExtensionAPI,
+  guard: SettleGuard,
+): void {
+  pi.events.on(SETTLE_PRIORITY_EVENT, (payload) => {
+    const request = payload as SettlePriorityRequest;
+    if (guard.pending(request.ctx)) {
+      request.priorities.add(guard.priority);
+    }
+  });
+
+  pi.on('agent_before_settle', (event, ctx) => {
+    if (!acceptsSettleSteer(event) || !guard.pending(ctx)) {
+      return;
+    }
+    const request: SettlePriorityRequest = { ctx, priorities: new Set() };
+    pi.events.emit(SETTLE_PRIORITY_EVENT, request);
+    if ([...request.priorities].some((priority) => priority < guard.priority)) {
+      return;
+    }
+    return guard.handle(event, ctx);
+  });
+}
+
 // 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 {
+interface HiddenSteerOptions {
+  readonly event: AgentBeforeSettleEvent;
+  readonly customType: string;
+  readonly content: string;
+}
+
+export function withHiddenSteer({
+  event,
+  customType,
+  content,
+}: HiddenSteerOptions): AgentBeforeSettleEventResult {
   return {
     entries: [
       ...event.entries,

package/extensions/visual-context/bridge.ts

@@ -0,0 +1,240 @@
+import { WebSocket } from 'ws';
+import { type LocalBroker, startBroker } from './broker.ts';
+import { parseEnvelope, send } from './envelope.ts';
+import {
+  MESSAGE_TYPE,
+  PEER_ROLE,
+  PI_ORIGIN,
+  PROTOCOL_VERSION,
+  parseSelection,
+  type SessionDescriptor,
+  type VisualSelection,
+} from './model.ts';
+import { endpoint, hasCode, type PairingIdentity } from './pairing.ts';
+
+const RECONNECT_MS = 1_000;
+const HEARTBEAT_MS = 20_000;
+const STARTUP_TIMEOUT_MS = 10_000;
+export interface VisualBridge {
+  update(session: SessionDescriptor): void;
+  close(): Promise<void>;
+}
+interface SessionConnectionOptions {
+  readonly identity: PairingIdentity;
+  readonly session: SessionDescriptor;
+  readonly onSelection: (
+    selection: VisualSelection,
+    revision: string,
+  ) => {
+    readonly candidates: number;
+  };
+  readonly onError: (error: Error) => void;
+}
+
+export async function connectSession(
+  options: SessionConnectionOptions,
+): Promise<VisualBridge> {
+  let session = options.session;
+  let broker: LocalBroker | undefined;
+  let socket: WebSocket | undefined;
+  let retry: NodeJS.Timeout | undefined;
+  let heartbeat: NodeJS.Timeout | undefined;
+  let closed = false;
+  let authenticated = false;
+  let registered = false;
+  let resolveStartup: () => void;
+  let rejectStartup: (error: Error) => void;
+  const startup = new Promise<void>((resolve, reject) => {
+    resolveStartup = resolve;
+    rejectStartup = reject;
+  });
+  const report = (cause: unknown): void => {
+    if (closed) {
+      return;
+    }
+    const error =
+      cause instanceof Error
+        ? cause
+        : new Error('Cannot connect the Pi session.', { cause });
+    if (!registered) {
+      rejectStartup(error);
+    } else {
+      options.onError(error);
+    }
+  };
+  const register = (): void => {
+    if (socket && authenticated) {
+      send(socket, { type: MESSAGE_TYPE.register, session });
+    }
+  };
+  async function attach(): Promise<void> {
+    if (closed) {
+      return;
+    }
+    if (!broker) {
+      try {
+        const created = await startBroker({
+          identity: options.identity,
+          onError: options.onError,
+        });
+        if (closed) {
+          await created.close();
+          return;
+        }
+        broker = created;
+      } catch (cause) {
+        if (!hasCode(cause, 'EADDRINUSE')) {
+          report(cause);
+          scheduleRetry();
+          return;
+        }
+      }
+    }
+    if (closed) {
+      return;
+    }
+    const connection = new WebSocket(endpoint(options.identity), {
+      origin: PI_ORIGIN,
+      maxPayload: 32_768,
+    });
+    socket = connection;
+    authenticated = false;
+    const authenticationTimeout = setTimeout(() => {
+      report(new Error('The local browser bridge did not authenticate.'));
+      connection.terminate();
+    }, STARTUP_TIMEOUT_MS);
+    authenticationTimeout.unref();
+    connection.on('open', () =>
+      send(connection, {
+        type: MESSAGE_TYPE.authenticate,
+        role: PEER_ROLE.pi,
+        version: PROTOCOL_VERSION,
+        token: options.identity.token,
+      }),
+    );
+    connection.on('error', report);
+    connection.on('close', () => {
+      clearTimeout(authenticationTimeout);
+      clearInterval(heartbeat);
+      authenticated = false;
+      scheduleRetry();
+    });
+    connection.on('message', (bytes, binary) => {
+      try {
+        const message = parseEnvelope(bytes.toString(), binary);
+        if (
+          message.type === MESSAGE_TYPE.ready &&
+          message.version === PROTOCOL_VERSION
+        ) {
+          clearTimeout(authenticationTimeout);
+          authenticated = true;
+          heartbeat = setInterval(
+            () => send(connection, { type: MESSAGE_TYPE.ping }),
+            HEARTBEAT_MS,
+          );
+          heartbeat.unref();
+          register();
+          return;
+        }
+        if (
+          message.type === MESSAGE_TYPE.register &&
+          message.revision === session.revision
+        ) {
+          registered = true;
+          resolveStartup();
+          return;
+        }
+        if (message.type === MESSAGE_TYPE.error) {
+          report(new Error(String(message.message)));
+          return;
+        }
+        if (message.type !== MESSAGE_TYPE.deliver) {
+          return;
+        }
+        try {
+          if (closed || message.revision !== session.revision) {
+            throw new Error(
+              'The Pi conversation changed. Select the element again.',
+            );
+          }
+          const receipt = options.onSelection(
+            parseSelection(message.selection),
+            session.revision,
+          );
+          send(connection, {
+            type: MESSAGE_TYPE.result,
+            requestId: message.requestId,
+            candidates: receipt.candidates,
+          });
+        } catch (cause) {
+          const error =
+            cause instanceof Error
+              ? cause
+              : new Error('Cannot receive browser selection.', { cause });
+          options.onError(error);
+          send(connection, {
+            type: MESSAGE_TYPE.result,
+            requestId: message.requestId,
+            error: error.message,
+          });
+        }
+      } catch (cause) {
+        report(cause);
+      }
+    });
+  }
+  function scheduleRetry(): void {
+    if (closed || retry) {
+      return;
+    }
+    retry = setTimeout(() => {
+      retry = undefined;
+      void attach().catch(report);
+    }, RECONNECT_MS);
+    retry.unref();
+  }
+  let closing: Promise<void> | undefined;
+  const bridge: VisualBridge = {
+    update(next) {
+      session = next;
+      register();
+    },
+    close() {
+      if (closing) {
+        return closing;
+      }
+      closed = true;
+      clearTimeout(retry);
+      clearInterval(heartbeat);
+      closing = (async () => {
+        if (socket && socket.readyState !== WebSocket.CLOSED) {
+          const disconnected = new Promise<void>((resolve) =>
+            socket?.once('close', resolve),
+          );
+          socket.terminate();
+          await disconnected;
+        }
+        await broker?.close();
+      })();
+      return closing;
+    },
+  };
+  const deadline = setTimeout(
+    () =>
+      rejectStartup(
+        new Error('The Pi session could not join the local browser bridge.'),
+      ),
+    STARTUP_TIMEOUT_MS,
+  );
+  deadline.unref();
+  void attach().catch(report);
+  try {
+    await startup;
+    return bridge;
+  } catch (cause) {
+    await bridge.close();
+    throw cause;
+  } finally {
+    clearTimeout(deadline);
+  }
+}