pi-jev-auto-mode 0.1.0

package/src/settings.ts

@@ -0,0 +1,274 @@
+/**
+ * Settings, policy notes, and the stored API key.
+ *
+ * Global settings live next to the rest of the Pi agent state
+ * (`$PI_CODING_AGENT_DIR` or `~/.pi/agent`). A project can override them from
+ * `<cwd>/<CONFIG_DIR_NAME>/jev-auto-mode.json`, but only for a trusted project:
+ * an untrusted checkout must not be able to loosen the gate that is judging it.
+ *
+ * The API key is not a setting. It goes to `<agentDir>/secrets/` as a `0600` file,
+ * which is where Pi keeps its own credentials, so that it is neither committed with
+ * a project nor readable by other users on the machine.
+ */
+
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export interface JevAutoModeSettings {
+  readonly enabled: boolean;
+  /** Per-attempt JEV timeout. Kept short: this is a gate, not a batch job. */
+  readonly timeoutMs: number;
+  /** Retries after the first attempt. */
+  readonly maxRetries: number;
+  /** Commands the user considers safe to run without a decision record. */
+  readonly safeCommands: readonly string[];
+  /** Commands that override a dangerous-pattern match; the override is recorded. */
+  readonly allowedCommands: readonly string[];
+  readonly disallowedCommands: readonly string[];
+  readonly extraProtectedPaths: readonly string[];
+  /** Shared state + questions budget guard, in characters. */
+  readonly maxStateCharacters: number;
+  /**
+   * Per-rule probability thresholds, overriding the calibrated defaults.
+   *
+   * Keys are rule ids. An unknown key is kept but has no effect, so a typo is
+   * visible in `/jev-auto-mode threshold` instead of silently resetting the rule.
+   */
+  readonly thresholds: Readonly<Record<string, number>>;
+}
+
+export type SettingsScope = "global" | "project";
+
+export const DEFAULT_SETTINGS: JevAutoModeSettings = {
+  enabled: true,
+  timeoutMs: 4000,
+  maxRetries: 1,
+  safeCommands: [],
+  allowedCommands: [],
+  disallowedCommands: [],
+  extraProtectedPaths: [],
+  maxStateCharacters: 120_000,
+  thresholds: {},
+};
+
+const MAX_PATTERN_ENTRIES = 200;
+const MAX_PATTERN_LENGTH = 300;
+const MAX_THRESHOLD_ENTRIES = 32;
+const MAX_RULE_ID_LENGTH = 64;
+const MAX_POLICY_NOTES_LENGTH = 8000;
+const CREDENTIAL_FILE_NAME = "jev-auto-mode-typesafe-api-key";
+/** Mirrors Pi's own secret directory/file modes. */
+const SECRET_DIRECTORY_MODE = 0o700;
+const SECRET_FILE_MODE = 0o600;
+const MIN_TIMEOUT_MS = 250;
+const MAX_TIMEOUT_MS = 60_000;
+const MAX_RETRIES = 5;
+
+/** A probability threshold must leave a middle band on both sides. */
+export const MIN_THRESHOLD = 0.5;
+export const MAX_THRESHOLD = 1;
+
+export interface StoreOptions {
+  /** Usually `~/.pi/agent`, honoring `PI_CODING_AGENT_DIR`. */
+  readonly agentDir: string;
+  /** Usually `.pi` (`CONFIG_DIR_NAME`). */
+  readonly configDirName: string;
+}
+
+export type SettingsPatch = { -readonly [K in keyof JevAutoModeSettings]?: JevAutoModeSettings[K] };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Validate a single threshold value. Returns `undefined` when it is not usable. */
+export function parseThreshold(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  if (value <= MIN_THRESHOLD || value > MAX_THRESHOLD) return undefined;
+  return value;
+}
+
+function readThresholds(value: unknown): Readonly<Record<string, number>> | undefined {
+  if (!isRecord(value)) return undefined;
+  const thresholds: Record<string, number> = {};
+  for (const [ruleId, raw] of Object.entries(value)) {
+    if (ruleId.length === 0 || ruleId.length > MAX_RULE_ID_LENGTH) continue;
+    const threshold = parseThreshold(raw);
+    if (threshold === undefined) continue;
+    thresholds[ruleId] = threshold;
+    if (Object.keys(thresholds).length >= MAX_THRESHOLD_ENTRIES) break;
+  }
+  return thresholds;
+}
+
+function readBoundedInteger(value: unknown, min: number, max: number): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  const rounded = Math.round(value);
+  if (rounded < min || rounded > max) return undefined;
+  return rounded;
+}
+
+function readStringArray(value: unknown): readonly string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  return value
+    .filter((entry): entry is string => typeof entry === "string")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0 && entry.length <= MAX_PATTERN_LENGTH && !entry.includes("\n"))
+    .slice(0, MAX_PATTERN_ENTRIES);
+}
+
+/**
+ * Validate an untrusted settings file.
+ *
+ * Malformed values are dropped rather than replaced by a default: a broken
+ * project file must not be able to pin a value that overrides the global layer.
+ * Unknown fields are ignored too.
+ */
+export function parseSettingsPatch(value: unknown): SettingsPatch {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const record = value as Record<string, unknown>;
+  const patch: SettingsPatch = {};
+
+  if (typeof record.enabled === "boolean") patch.enabled = record.enabled;
+
+  const timeoutMs = readBoundedInteger(record.timeoutMs, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS);
+  if (timeoutMs !== undefined) patch.timeoutMs = timeoutMs;
+
+  const maxRetries = readBoundedInteger(record.maxRetries, 0, MAX_RETRIES);
+  if (maxRetries !== undefined) patch.maxRetries = maxRetries;
+
+  const maxStateCharacters = readBoundedInteger(record.maxStateCharacters, 1000, 1_000_000);
+  if (maxStateCharacters !== undefined) patch.maxStateCharacters = maxStateCharacters;
+
+  const safeCommands = record.safeCommands === undefined ? undefined : readStringArray(record.safeCommands);
+  if (safeCommands !== undefined) patch.safeCommands = safeCommands;
+
+  const allowedCommands = record.allowedCommands === undefined ? undefined : readStringArray(record.allowedCommands);
+  if (allowedCommands !== undefined) patch.allowedCommands = allowedCommands;
+
+  const disallowedCommands =
+    record.disallowedCommands === undefined ? undefined : readStringArray(record.disallowedCommands);
+  if (disallowedCommands !== undefined) patch.disallowedCommands = disallowedCommands;
+
+  const extraProtectedPaths =
+    record.extraProtectedPaths === undefined ? undefined : readStringArray(record.extraProtectedPaths);
+  if (extraProtectedPaths !== undefined) patch.extraProtectedPaths = extraProtectedPaths;
+
+  const thresholds = record.thresholds === undefined ? undefined : readThresholds(record.thresholds);
+  if (thresholds !== undefined) patch.thresholds = thresholds;
+
+  return patch;
+}
+
+export function mergeSettings(base: JevAutoModeSettings, patch: SettingsPatch): JevAutoModeSettings {
+  const merged = { ...base, ...patch };
+  // Thresholds merge per rule: a project file that retunes one condition must not
+  // wipe the global overrides for the others.
+  if (patch.thresholds !== undefined) {
+    merged.thresholds = { ...base.thresholds, ...patch.thresholds };
+  }
+  return merged;
+}
+
+async function readJsonFile(path: string): Promise<unknown> {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+async function writeFileAtomic(path: string, contents: string): Promise<void> {
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(temporary, contents, "utf8");
+  await rename(temporary, path);
+}
+
+export class JevAutoModeStore {
+  private readonly agentDir: string;
+  private readonly configDirName: string;
+
+  constructor(options: StoreOptions) {
+    this.agentDir = options.agentDir;
+    this.configDirName = options.configDirName;
+  }
+
+  globalSettingsPath(): string {
+    return join(this.agentDir, "jev-auto-mode.json");
+  }
+
+  projectSettingsPath(cwd: string): string {
+    return join(cwd, this.configDirName, "jev-auto-mode.json");
+  }
+
+  policyNotesPath(): string {
+    return join(this.agentDir, "jev-auto-mode-policy.md");
+  }
+
+  /** Global settings with the project override layered on top, when trusted. */
+  async loadSettings(cwd: string, projectTrusted: boolean): Promise<{ settings: JevAutoModeSettings; scope: SettingsScope }> {
+    const globalPatch = parseSettingsPatch(await readJsonFile(this.globalSettingsPath()));
+    if (!projectTrusted) {
+      return { settings: mergeSettings(DEFAULT_SETTINGS, globalPatch), scope: "global" };
+    }
+    const projectValue = await readJsonFile(this.projectSettingsPath(cwd));
+    const hasProjectSettings = projectValue !== undefined;
+    const projectPatch = parseSettingsPatch(projectValue);
+    return {
+      settings: mergeSettings(mergeSettings(DEFAULT_SETTINGS, globalPatch), projectPatch),
+      scope: hasProjectSettings ? "project" : "global",
+    };
+  }
+
+  async saveSettings(settings: JevAutoModeSettings, scope: SettingsScope, cwd: string): Promise<void> {
+    const path = scope === "project" ? this.projectSettingsPath(cwd) : this.globalSettingsPath();
+    await writeFileAtomic(path, `${JSON.stringify(settings, null, 2)}\n`);
+  }
+
+  /** User-authored policy notes. Advisory input to JEV, never a hard rule. */
+  async loadPolicyNotes(): Promise<string> {
+    try {
+      return (await readFile(this.policyNotesPath(), "utf8")).slice(0, MAX_POLICY_NOTES_LENGTH);
+    } catch {
+      return "";
+    }
+  }
+
+  async savePolicyNotes(notes: string): Promise<void> {
+    await writeFileAtomic(this.policyNotesPath(), notes.slice(0, MAX_POLICY_NOTES_LENGTH));
+  }
+
+  credentialPath(): string {
+    return join(this.agentDir, "secrets", CREDENTIAL_FILE_NAME);
+  }
+
+  async readStoredApiKey(): Promise<string | undefined> {
+    try {
+      const value = (await readFile(this.credentialPath(), "utf8")).trim();
+      return value.length > 0 ? value : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Store the API key with owner-only permissions.
+   *
+   * `mode` on `writeFile` only applies when the file is created, so the mode is set
+   * again afterwards: an existing file with looser permissions is tightened rather
+   * than trusted.
+   */
+  async writeStoredApiKey(apiKey: string): Promise<void> {
+    const path = this.credentialPath();
+    const directory = dirname(path);
+    await mkdir(directory, { recursive: true, mode: SECRET_DIRECTORY_MODE });
+    await chmod(directory, SECRET_DIRECTORY_MODE).catch(() => undefined);
+    await writeFile(path, `${apiKey.trim()}\n`, { encoding: "utf8", mode: SECRET_FILE_MODE });
+    await chmod(path, SECRET_FILE_MODE).catch(() => undefined);
+  }
+
+  async deleteStoredApiKey(): Promise<void> {
+    await rm(this.credentialPath(), { force: true });
+  }
+}

package/src/ui.ts

@@ -0,0 +1,125 @@
+/**
+ * Footer status and user-facing text.
+ *
+ * The status line is the only always-visible signal that a probabilistic gate is
+ * standing between the model and the shell, so it stays short but never silent:
+ * "off" and "no decision engine" are different states and are shown differently.
+ */
+
+import type { JevAutoModeSettings, SettingsScope } from "./settings.ts";
+import { DEFAULT_RULES, type JevRule } from "./jev/questions.ts";
+import { formatThreshold, observe } from "./jev/decide.ts";
+
+export const STATUS_ID = "jev-auto-mode";
+
+export interface StatusInput {
+  readonly enabled: boolean;
+  readonly engineId: string;
+  readonly scope: SettingsScope;
+}
+
+export function statusText(input: StatusInput): string {
+  if (!input.enabled) return "🛡 jev off";
+  const scope = input.scope === "project" ? "project" : "global";
+  const engine = input.engineId === "manual" ? " ask-only" : "";
+  return `🛡 jev${engine} (${scope})`;
+}
+
+export interface StatusContext {
+  readonly ui: { setStatus(key: string, value: string | undefined): void };
+}
+
+export function updateStatus(ctx: StatusContext, input: StatusInput): void {
+  ctx.ui.setStatus(STATUS_ID, statusText(input));
+}
+
+export function describeSettings(settings: JevAutoModeSettings, scope: SettingsScope): string {
+  return [
+    `enabled: ${settings.enabled}`,
+    `scope: ${scope}`,
+    `timeout: ${settings.timeoutMs}ms (retries ${settings.maxRetries})`,
+    `safe commands: ${settings.safeCommands.length}`,
+    `allowed commands: ${settings.allowedCommands.length}`,
+    `disallowed commands: ${settings.disallowedCommands.length}`,
+    `extra protected paths: ${settings.extraProtectedPaths.length}`,
+    `max state characters: ${settings.maxStateCharacters}`,
+  ].join("\n");
+}
+
+export const USAGE_TEXT = [
+  "Usage:",
+  "  /jev-auto-mode                     show status",
+  "  /jev-auto-mode on|off              toggle auto mode",
+  "  /jev-auto-mode login|logout        store or remove the TypeSafe API key",
+  "  /jev-auto-mode policy              list the user policy notes",
+  "  /jev-auto-mode policy edit",
+  "  /jev-auto-mode policy clear",
+  "  /jev-auto-mode threshold           show thresholds and last observed probabilities",
+  "  /jev-auto-mode threshold <rule> <0.5-1.0>",
+  "  /jev-auto-mode threshold reset [rule]",
+].join("\n");
+
+export const POLICY_HEADER = [
+  "# JEV auto mode policy",
+  "",
+  "Free-form notes describing what this machine and these repositories allow.",
+  "They are reference material for the semantic judgment: they can justify an",
+  "approval, but they cannot override hard-deny rules.",
+].join("\n");
+
+/**
+ * The most recent judgment of one condition, kept for threshold tuning.
+ *
+ * Only the probability is stored. The band is recomputed against the *current*
+ * threshold, so changing a threshold immediately shows what the last judgment would
+ * have become — storing the band would leave a stale label next to a threshold that
+ * no longer produced it.
+ */
+export interface ObservedCondition {
+  readonly probability: number;
+  readonly at: number;
+}
+
+function pad(value: string, width: number): string {
+  return value.length >= width ? value : value + " ".repeat(width - value.length);
+}
+
+/**
+ * The tuning table.
+ *
+ * Showing the last observed probability next to each threshold is the whole point:
+ * a threshold cannot be chosen from a rule description, only from what the model
+ * actually answered for calls you care about. The band is recomputed against the
+ * current threshold, so the table doubles as a what-if view while tuning.
+ */
+export function formatRuleTable(
+  rules: readonly JevRule[] = DEFAULT_RULES,
+  overrides: Readonly<Record<string, number>> = {},
+  observed: ReadonlyMap<string, ObservedCondition> = new Map(),
+): string {
+  const header = `${pad("rule", 24)}${pad("mode", 10)}${pad("severity", 10)}${pad("threshold", 30)}last observed`;
+  const rows = rules.map((rule) => {
+    const override = overrides[rule.id];
+    const threshold = override ?? rule.threshold;
+    const origin = override === undefined ? "default" : `override (default ${formatThreshold(rule.threshold)})`;
+    // Recompute against the effective rule, not the default one: the point of the
+    // last-observed column is to answer "what would this answer mean now".
+    const effective = override === undefined ? rule : { ...rule, threshold: override };
+    return `${pad(rule.id, 24)}${pad(rule.mode, 10)}${pad(rule.severity, 10)}${pad(`${formatThreshold(threshold)} ${origin}`, 30)}${describeLast(effective, observed.get(rule.id))}`;
+  });
+
+  const unknown = Object.keys(overrides).filter((ruleId) => !rules.some((rule) => rule.id === ruleId));
+  if (unknown.length > 0) {
+    rows.push(`\noverride(s) that match no known rule: ${unknown.join(", ")}`);
+  }
+
+  return [header, ...rows].join("\n");
+}
+
+function describeLast(rule: JevRule, last: ObservedCondition | undefined): string {
+  if (!last) return "-";
+  const [observation] = observe([rule], { [rule.id]: last.probability });
+  const band = observation?.verdict ?? "uncertain";
+  const label = band === "uncertain" && observation?.effective === "satisfied" ? "ignored" : band;
+  return `p=${last.probability.toFixed(2)} (${label})`;
+}