@rmrdeveloper/sideroom-pi 8.7.0 → 8.9.0

package/extensions/jev/guard.ts

@@ -0,0 +1,256 @@
+import {
+  type ExtensionAPI,
+  type ExtensionContext,
+  isEditToolResult,
+  isToolCallEventType,
+  isWriteToolResult,
+  type ToolCallEvent,
+} from '@earendil-works/pi-coding-agent';
+import { resolveFileToolPath } from '../shared/file-path.ts';
+import { readFileIfExists } from '../shared/read-file.ts';
+import {
+  askJev,
+  JEV_FAILURE,
+  type JevFailure,
+  type JevTransport,
+} from './client.ts';
+import {
+  type AddedLine,
+  addedLinesForEdit,
+  addedLinesForWrite,
+  buildFileState,
+  findingKey,
+  formatFindings,
+  type JevFinding,
+  stateFitsBudget,
+} from './model.ts';
+
+export const JEV_TRANSIENT_FAILURE_LIMIT = 3;
+
+const MUTATION_KIND = {
+  write: 'write',
+  edit: 'edit',
+} as const;
+
+export const JEV_STATUS = {
+  ready: 'ready',
+  noKey: 'noKey',
+  quota: 'quota',
+  auth: 'auth',
+  unavailable: 'unavailable',
+} as const;
+
+export type JevStatus = (typeof JEV_STATUS)[keyof typeof JEV_STATUS];
+
+interface PendingMutation {
+  readonly path: string;
+  readonly kind: string;
+  readonly lines: readonly AddedLine[];
+}
+
+export interface JevGuardState {
+  halted: JevStatus | undefined;
+  transientFailures: number;
+  lastModel: string | undefined;
+  calls: number;
+  readonly pending: Map<string, PendingMutation>;
+  readonly notedThisTurn: Set<string>;
+}
+
+export interface JevGuardDependencies {
+  readonly apiKey: () => string | undefined;
+  readonly transport: JevTransport;
+  readonly report: (status: JevStatus, ctx: ExtensionContext) => void;
+}
+
+export function createJevGuardState(): JevGuardState {
+  return {
+    halted: undefined,
+    transientFailures: 0,
+    lastModel: undefined,
+    calls: 0,
+    pending: new Map(),
+    notedThisTurn: new Set(),
+  };
+}
+
+// The F10 screen calls this after the user stores a key or asks to retry.
+export function resetJevGuard(state: JevGuardState): void {
+  state.halted = undefined;
+  state.transientFailures = 0;
+}
+
+// Usage belongs to the active session: a new session starts counting from zero.
+export function resetJevUsage(state: JevGuardState): void {
+  state.calls = 0;
+}
+
+export function guardStatus(state: JevGuardState): JevStatus {
+  if (state.halted !== undefined) {
+    return state.halted;
+  }
+  return state.transientFailures > 0
+    ? JEV_STATUS.unavailable
+    : JEV_STATUS.ready;
+}
+
+export function shouldCallJev(state: JevGuardState): boolean {
+  return (
+    state.halted === undefined &&
+    state.transientFailures < JEV_TRANSIENT_FAILURE_LIMIT
+  );
+}
+
+export function registerJevGuard(
+  pi: ExtensionAPI,
+  state: JevGuardState,
+  dependencies: JevGuardDependencies,
+): void {
+  pi.on('input', (event) => {
+    if (event.source !== 'interactive' && event.source !== 'rpc') {
+      return;
+    }
+    state.notedThisTurn.clear();
+  });
+
+  // The added lines are read before the mutation lands, because after a write
+  // the previous content is gone. The body is read after, from disk.
+  pi.on('tool_call', (event, ctx) => {
+    const mutation = extractMutation(event, ctx.cwd);
+    if (mutation === undefined) {
+      return undefined;
+    }
+    state.pending.set(event.toolCallId, mutation);
+    return undefined;
+  });
+
+  pi.on('tool_result', async (event, ctx) => {
+    const pending = state.pending.get(event.toolCallId);
+    state.pending.delete(event.toolCallId);
+    if (pending === undefined || event.isError) {
+      return undefined;
+    }
+    if (!isWriteToolResult(event) && !isEditToolResult(event)) {
+      return undefined;
+    }
+
+    const apiKey = dependencies.apiKey();
+    if (apiKey === undefined) {
+      dependencies.report(JEV_STATUS.noKey, ctx);
+      return undefined;
+    }
+    if (!shouldCallJev(state)) {
+      dependencies.report(guardStatus(state), ctx);
+      return undefined;
+    }
+
+    const body = readMutationBody(ctx.cwd, pending.path);
+    if (body === undefined || !stateFitsBudget(body)) {
+      return undefined;
+    }
+
+    state.calls += 1;
+    const attempt = await askJev(
+      dependencies.transport,
+      apiKey,
+      buildFileState(pending.path, body, pending.kind, pending.lines),
+    );
+    if (attempt.failure !== undefined) {
+      registerFailure(state, attempt.failure);
+      dependencies.report(guardStatus(state), ctx);
+      return undefined;
+    }
+
+    registerSuccess(state);
+    if (attempt.model !== undefined) {
+      state.lastModel = attempt.model;
+    }
+    dependencies.report(JEV_STATUS.ready, ctx);
+
+    const findings = attempt.findings ?? [];
+    const fresh = findings.filter((finding) =>
+      isUnnoted(state, pending.path, finding),
+    );
+    if (fresh.length === 0) {
+      return undefined;
+    }
+    markNoted(state, pending.path, fresh);
+    return {
+      content: [
+        ...event.content,
+        { type: 'text' as const, text: formatFindings(pending.path, fresh) },
+      ],
+    };
+  });
+}
+
+function isUnnoted(
+  state: JevGuardState,
+  path: string,
+  finding: JevFinding,
+): boolean {
+  return !state.notedThisTurn.has(findingKey(path, finding.ruleId));
+}
+
+function markNoted(
+  state: JevGuardState,
+  path: string,
+  findings: readonly JevFinding[],
+): void {
+  for (const finding of findings) {
+    state.notedThisTurn.add(findingKey(path, finding.ruleId));
+  }
+}
+
+function registerFailure(state: JevGuardState, failure: JevFailure): void {
+  if (failure === JEV_FAILURE.quota) {
+    state.halted = JEV_STATUS.quota;
+    return;
+  }
+  if (failure === JEV_FAILURE.auth) {
+    state.halted = JEV_STATUS.auth;
+    return;
+  }
+  state.transientFailures += 1;
+  if (state.transientFailures >= JEV_TRANSIENT_FAILURE_LIMIT) {
+    state.halted = JEV_STATUS.unavailable;
+  }
+}
+
+function registerSuccess(state: JevGuardState): void {
+  state.halted = undefined;
+  state.transientFailures = 0;
+}
+
+function extractMutation(
+  event: ToolCallEvent,
+  cwd: string,
+): PendingMutation | undefined {
+  if (isToolCallEventType('write', event)) {
+    const absolutePath = resolveFileToolPath(cwd, event.input.path);
+    return {
+      path: event.input.path,
+      kind: MUTATION_KIND.write,
+      lines: addedLinesForWrite(
+        absolutePath === undefined ? undefined : readFileIfExists(absolutePath),
+        event.input.content,
+      ),
+    };
+  }
+  if (isToolCallEventType('edit', event)) {
+    return {
+      path: event.input.path,
+      kind: MUTATION_KIND.edit,
+      lines: addedLinesForEdit(event.input.edits),
+    };
+  }
+  return undefined;
+}
+
+function readMutationBody(cwd: string, path: string): string | undefined {
+  const absolutePath = resolveFileToolPath(cwd, path);
+  if (absolutePath === undefined) {
+    return undefined;
+  }
+  return readFileIfExists(absolutePath);
+}

package/extensions/jev/index.ts

@@ -0,0 +1,88 @@
+import {
+  type ExtensionAPI,
+  type ExtensionContext,
+  getAgentDir,
+} from '@earendil-works/pi-coding-agent';
+import { createFetchTransport } from './client.ts';
+import {
+  createJevGuardState,
+  guardStatus,
+  JEV_STATUS,
+  type JevStatus,
+  registerJevGuard,
+  resetJevGuard,
+  resetJevUsage,
+} from './guard.ts';
+import {
+  clearStoredKey,
+  configPathFor,
+  resolveApiKey,
+  storeApiKey,
+} from './key.ts';
+import {
+  createJevKeyController,
+  JEV_SHORTCUT,
+  JEV_STATUS_KEY,
+  statusLabel,
+} from './ui.ts';
+
+// Pi loads extensions/*/index.ts through export default.
+export default function registerJev(pi: ExtensionAPI): void {
+  const configPath = configPathFor(getAgentDir());
+  const guardState = createJevGuardState();
+
+  // The key is read on each use instead of cached at load time, so a key stored
+  // during a running session takes effect without a restart.
+  const readKey = () => resolveApiKey(process.env, configPath);
+
+  const currentStatus = (): JevStatus => {
+    if (readKey() === undefined) {
+      return JEV_STATUS.noKey;
+    }
+    return guardStatus(guardState);
+  };
+
+  const publish = (status: JevStatus, ctx: ExtensionContext): void => {
+    ctx.ui.setStatus(
+      JEV_STATUS_KEY,
+      statusLabel(status, guardState.lastModel, guardState.calls),
+    );
+  };
+
+  const keyController = createJevKeyController({
+    store: (apiKey) => {
+      storeApiKey(configPath, apiKey);
+    },
+    clear: () => {
+      clearStoredKey(configPath);
+    },
+    retry: () => {
+      resetJevGuard(guardState);
+    },
+    origin: () => readKey()?.origin,
+    usage: () => guardState.calls,
+    refresh: (ctx) => {
+      publish(currentStatus(), ctx);
+    },
+  });
+
+  registerJevGuard(pi, guardState, {
+    apiKey: () => readKey()?.key,
+    transport: createFetchTransport(),
+    report: (status, ctx) => {
+      publish(status, ctx);
+    },
+  });
+
+  pi.on('session_start', (_event, ctx) => {
+    resetJevUsage(guardState);
+    publish(currentStatus(), ctx);
+  });
+
+  pi.registerShortcut(JEV_SHORTCUT, {
+    description: 'Set or clear the Jev API key',
+    handler: (ctx) => {
+      keyController.open(ctx);
+    },
+  });
+}

package/extensions/jev/key.ts

@@ -0,0 +1,95 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const JEV_KEY_ENV_VAR = 'TYPESAFE_API_KEY';
+export const SIDEROOM_CONFIG_FILE = 'sideroom.json';
+
+const JEV_API_KEY_FIELD = 'jevApiKey';
+const OWNER_ONLY_FILE_MODE = 0o600;
+const OWNER_ONLY_DIRECTORY_MODE = 0o700;
+
+export interface JevKeySource {
+  readonly key: string;
+  readonly origin: 'environment' | 'config';
+}
+
+export function configPathFor(agentDirectory: string): string {
+  return join(agentDirectory, SIDEROOM_CONFIG_FILE);
+}
+
+// The environment wins so containers and CI work with no file at all. A missing
+// or malformed config means "no key"; anything else about the file is a real
+// problem and surfaces instead of hiding.
+export function resolveApiKey(
+  environment: Readonly<Record<string, string | undefined>>,
+  configPath: string,
+): JevKeySource | undefined {
+  const fromEnvironment = environment[JEV_KEY_ENV_VAR]?.trim();
+  if (fromEnvironment !== undefined && fromEnvironment.length > 0) {
+    return { key: fromEnvironment, origin: 'environment' };
+  }
+  const stored = readStoredKey(configPath);
+  if (stored === undefined) {
+    return undefined;
+  }
+  return { key: stored, origin: 'config' };
+}
+
+export function readStoredKey(configPath: string): string | undefined {
+  let raw: string;
+  try {
+    raw = readFileSync(configPath, 'utf8');
+  } catch (error) {
+    if (isMissingFile(error)) {
+      return undefined;
+    }
+    throw error;
+  }
+
+  const parsed = parseConfig(raw);
+  if (parsed === undefined) {
+    return undefined;
+  }
+  const stored = parsed[JEV_API_KEY_FIELD];
+  if (typeof stored !== 'string') {
+    return undefined;
+  }
+  const trimmed = stored.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export function storeApiKey(configPath: string, apiKey: string): void {
+  mkdirSync(dirname(configPath), {
+    recursive: true,
+    mode: OWNER_ONLY_DIRECTORY_MODE,
+  });
+  const payload = `${JSON.stringify({ [JEV_API_KEY_FIELD]: apiKey }, null, 2)}\n`;
+  writeFileSync(configPath, payload, {
+    encoding: 'utf8',
+    mode: OWNER_ONLY_FILE_MODE,
+  });
+}
+
+export function clearStoredKey(configPath: string): void {
+  rmSync(configPath, { force: true });
+}
+
+function parseConfig(raw: string): Record<string, unknown> | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      return undefined;
+    }
+    throw error;
+  }
+  if (typeof parsed !== 'object' || parsed === null) {
+    return undefined;
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function isMissingFile(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}

package/extensions/jev/model.ts

@@ -0,0 +1,259 @@
+import { languageForPath } from '../rules/catalog.ts';
+import { type AddedLine, addedLines } from '../rules/model.ts';
+
+export type { AddedLine } from '../rules/model.ts';
+
+export const JEV_ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
+export const JEV_MODEL = 'jev-latest';
+
+// A noul answer carries a probability and no confidence, so this cutoff is the
+// only brake. Below it Jev is saying it has nothing to go on, which would be
+// noise on every edit.
+export const VIOLATION_PROBABILITY = 0.8;
+
+// The state must stay well under the two documented budgets (64k tokens for the
+// whole request, 32k for the state plus the longest question). A file that does
+// not fit is skipped, never truncated: half a file reads as a distorted picture
+// and Jev answers it with the same confidence.
+export const MAX_STATE_CHARACTERS = 60_000;
+
+const NOUL_TYPE = 'noul';
+
+export interface JevNoulQuestion {
+  readonly type: typeof NOUL_TYPE;
+  readonly instructions: string;
+  readonly criteria: { readonly true: string; readonly false: string };
+}
+
+export interface JevRule {
+  readonly id: string;
+  readonly question: JevNoulQuestion;
+}
+
+// The six guide rules that a single file can answer and that no mechanical
+// check covers. Rules 11, 12, 15, 16, 17 and 18 need the module's neighbours.
+export const JEV_RULES: readonly JevRule[] = [
+  {
+    id: 'guard-clauses',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'In `change.addedLines`, is the control flow nested so the main path is buried, instead of validating and exiting early?',
+      criteria: {
+        true: 'Conditionals nest two or more levels deep, or the main path sits inside a condition that could have returned early',
+        false:
+          'Each condition is handled with an early return or a flat sequence',
+      },
+    },
+  },
+  {
+    id: 'fail-fast',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'In `change.addedLines`, is an invalid or impossible state papered over with a silent fallback instead of failing immediately?',
+      criteria: {
+        true: 'A default value or a silent coercion hides a broken dependency or a state that should never happen',
+        false:
+          'An impossible or invalid case throws with a clear message, or no such case appears',
+      },
+    },
+  },
+  {
+    id: 'command-query',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'In `change.addedLines`, does a function both change state and return a value, or does something that reads like a query have a side effect?',
+      criteria: {
+        true: 'A function that returns data also mutates state, or a getter mutates',
+        false: 'Functions either change state or return data, never both',
+      },
+    },
+  },
+  {
+    id: 'null-handling',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'In `change.addedLines`, is the same empty value reused to mean several different states, or are `null` and `undefined` mixed for one meaning?',
+      criteria: {
+        true: 'One empty value carries more than one business meaning, or null and undefined stand for the same thing in different places',
+        false:
+          'One convention is used and each distinct state has its own value',
+      },
+    },
+  },
+  {
+    id: 'immutability',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'In `change.addedLines`, is an object or array received as a parameter modified in place?',
+      criteria: {
+        true: 'A parameter is pushed, assigned or deleted into, or a transform writes to state outside itself',
+        false: 'New values are returned instead of changing the inputs',
+      },
+    },
+  },
+  {
+    id: 'validate-once',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'In `change.addedLines`, is the same required, type or range check repeated after a boundary already owns that input?',
+      criteria: {
+        true: 'A rule already validated at the boundary is checked again deeper in the code',
+        false: 'Validation happens once, at the boundary that owns the input',
+      },
+    },
+  },
+];
+
+export interface JevFileState {
+  readonly file: {
+    readonly path: string;
+    readonly language: string;
+    readonly body: string;
+  };
+  readonly change: {
+    readonly kind: string;
+    readonly addedLines: readonly string[];
+  };
+}
+
+export interface JevRequestBody {
+  readonly model: string;
+  readonly state: JevFileState;
+  readonly questions: Readonly<Record<string, JevNoulQuestion>>;
+}
+
+export interface JevNoulAnswer {
+  readonly noul: number;
+}
+
+export interface JevResponseEnvelope {
+  readonly model: string | undefined;
+  readonly answers: Readonly<Record<string, JevNoulAnswer>> | undefined;
+}
+
+export interface JevFinding {
+  readonly ruleId: string;
+  readonly probability: number;
+}
+
+export function buildFileState(
+  path: string,
+  body: string,
+  kind: string,
+  lines: readonly AddedLine[],
+): JevFileState {
+  return {
+    file: { path, language: languageForPath(path), body },
+    change: { kind, addedLines: lines.map((line) => line.text) },
+  };
+}
+
+export function addedLinesForWrite(
+  previous: string | undefined,
+  next: string,
+): AddedLine[] {
+  return addedLines(previous, next);
+}
+
+export function addedLinesForEdit(
+  edits: readonly { readonly oldText: string; readonly newText: string }[],
+): AddedLine[] {
+  return edits.flatMap((edit) => addedLines(edit.oldText, edit.newText));
+}
+
+export function stateFitsBudget(body: string): boolean {
+  return body.length <= MAX_STATE_CHARACTERS;
+}
+
+export function buildRequestBody(file: JevFileState): JevRequestBody {
+  const questions: Record<string, JevNoulQuestion> = {};
+  for (const rule of JEV_RULES) {
+    questions[rule.id] = rule.question;
+  }
+  return { model: JEV_MODEL, state: file, questions };
+}
+
+export function parseEnvelope(text: string): JevResponseEnvelope | undefined {
+  const payload = parseJsonObject(text);
+  if (payload === undefined) {
+    return undefined;
+  }
+  const model = typeof payload.model === 'string' ? payload.model : undefined;
+  return { model, answers: readAnswers(payload.answers) };
+}
+
+export function readFindings(
+  envelope: JevResponseEnvelope,
+): readonly JevFinding[] {
+  const answers = envelope.answers;
+  if (answers === undefined) {
+    return [];
+  }
+  const findings: JevFinding[] = [];
+  for (const rule of JEV_RULES) {
+    const answer = answers[rule.id];
+    if (answer === undefined || answer.noul < VIOLATION_PROBABILITY) {
+      continue;
+    }
+    findings.push({ ruleId: rule.id, probability: answer.noul });
+  }
+  return findings;
+}
+
+export function findingKey(path: string, ruleId: string): string {
+  return `${path}#${ruleId}`;
+}
+
+export function formatFindings(
+  path: string,
+  findings: readonly JevFinding[],
+): string {
+  return [
+    `Sideroom Jev review flagged ${path}:`,
+    ...findings.map(
+      (finding) =>
+        `- [${finding.ruleId}] Jev scored ${finding.probability.toFixed(2)} probability that the added lines break this rule. Verify against the loaded guide before changing anything.`,
+    ),
+  ].join('\n');
+}
+
+function parseJsonObject(text: string): Record<string, unknown> | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      return undefined;
+    }
+    throw error;
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return undefined;
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function readAnswers(
+  value: unknown,
+): Record<string, JevNoulAnswer> | undefined {
+  if (typeof value !== 'object' || value === null) {
+    return undefined;
+  }
+  const answers: Record<string, JevNoulAnswer> = {};
+  for (const [id, entry] of Object.entries(value)) {
+    if (typeof entry !== 'object' || entry === null) {
+      continue;
+    }
+    const { noul } = entry as { noul?: unknown };
+    if (typeof noul === 'number') {
+      answers[id] = { noul };
+    }
+  }
+  return answers;
+}