pi-observability 1.0.1 → 1.3.0

package/extensions/lib/settings/domain.ts

@@ -0,0 +1,161 @@
+import { DEFAULT_SETTINGS, PRESETS } from "./metadata.js";
+import type { PresetName, SegmentKey, SettingsConfig, SettingsUpdateResult } from "./types.js";
+
+export function createDefaultSettings(): SettingsConfig {
+  return structuredClone(DEFAULT_SETTINGS);
+}
+
+export function applyPreset(config: SettingsConfig, preset: PresetName): SettingsConfig {
+  const next = structuredClone(config);
+  next.preset = preset;
+  const p = PRESETS[preset];
+  for (const [key, val] of Object.entries(p) as [SegmentKey, boolean][]) {
+    next.segments[key] = val;
+  }
+  return next;
+}
+
+export function toggleSegment(config: SettingsConfig, key: SegmentKey): SettingsConfig {
+  const next = structuredClone(config);
+  next.segments[key] = !next.segments[key];
+  return next;
+}
+
+export function setSegment(
+  config: SettingsConfig,
+  key: SegmentKey,
+  value: boolean,
+): SettingsConfig {
+  const next = structuredClone(config);
+  next.segments[key] = value;
+  return next;
+}
+
+export function setZone(
+  config: SettingsConfig,
+  key: "expert" | "warning",
+  value: number,
+): SettingsConfig {
+  const next = structuredClone(config);
+  next.contextZones[key] = Math.max(0, Math.min(100, value));
+  // Ensure expert <= warning
+  if (next.contextZones.expert > next.contextZones.warning) {
+    if (key === "expert") {
+      next.contextZones.warning = next.contextZones.expert;
+    } else {
+      next.contextZones.expert = next.contextZones.warning;
+    }
+  }
+  return next;
+}
+
+export function validateSettings(raw: unknown): SettingsConfig {
+  if (!raw || typeof raw !== "object") {
+    return createDefaultSettings();
+  }
+  const r = raw as Record<string, unknown>;
+
+  const preset = isPresetName(r.preset) ? r.preset : DEFAULT_SETTINGS.preset;
+  const segments = validateSegments(r.segments);
+  const contextZones = validateZones(r.contextZones);
+
+  return { version: 1, preset, segments, contextZones };
+}
+
+export function migrateSettings(raw: unknown): SettingsConfig {
+  const validated = validateSettings(raw);
+  // If we ever need version migrations, add them here
+  return validated;
+}
+
+export function updateSetting(
+  config: SettingsConfig,
+  id: string,
+  value: string,
+): SettingsUpdateResult {
+  let next = structuredClone(config);
+  const derivedUpdates: Array<{ id: string; value: string }> = [];
+
+  switch (id) {
+    case "preset": {
+      if (isPresetName(value)) {
+        next = applyPreset(next, value);
+        for (const key of Object.keys(next.segments) as SegmentKey[]) {
+          derivedUpdates.push({ id: key, value: next.segments[key] ? "true" : "false" });
+        }
+      }
+      break;
+    }
+    case "modelThink":
+    case "runtime":
+    case "pwd":
+    case "git":
+    case "contextUsage":
+    case "contextProgress":
+    case "contextPercentage":
+    case "contextNumbers":
+    case "tokens":
+    case "tps":
+    case "cost": {
+      next = setSegment(next, id, value === "true");
+      // Context sub-toggle dependency: if contextUsage is turned off, children are hidden
+      if (id === "contextUsage" && value === "false") {
+        for (const child of [
+          "contextProgress",
+          "contextPercentage",
+          "contextNumbers",
+        ] as SegmentKey[]) {
+          derivedUpdates.push({ id: child, value: "false" });
+        }
+      }
+      break;
+    }
+    case "expertZone": {
+      next = setZone(next, "expert", parseInt(value, 10));
+      break;
+    }
+    case "warningZone": {
+      next = setZone(next, "warning", parseInt(value, 10));
+      break;
+    }
+  }
+
+  return { config: next, derivedUpdates };
+}
+
+function isPresetName(v: unknown): v is PresetName {
+  return v === "minimal" || v === "standard" || v === "verbose" || v === "performance";
+}
+
+function validateSegments(raw: unknown): Record<SegmentKey, boolean> {
+  const segments = { ...DEFAULT_SETTINGS.segments };
+  if (!raw || typeof raw !== "object") return segments;
+  for (const [key, val] of Object.entries(raw)) {
+    if (key in segments && typeof val === "boolean") {
+      segments[key as SegmentKey] = val;
+    }
+  }
+  return segments;
+}
+
+function validateZones(raw: unknown): { expert: number; warning: number } {
+  const zones = { ...DEFAULT_SETTINGS.contextZones };
+  if (!raw || typeof raw !== "object") return zones;
+  const r = raw as Record<string, unknown>;
+
+  if (typeof r.expert === "number") zones.expert = clamp(0, r.expert, 100);
+  if (typeof r.warning === "number") zones.warning = clamp(0, r.warning, 100);
+
+  // Ensure expert <= warning
+  if (zones.expert > zones.warning) {
+    const avg = Math.round((zones.expert + zones.warning) / 2);
+    zones.expert = avg;
+    zones.warning = avg;
+  }
+
+  return zones;
+}
+
+function clamp(min: number, val: number, max: number): number {
+  return Math.max(min, Math.min(max, val));
+}

package/extensions/lib/settings/index.ts

@@ -0,0 +1,32 @@
+export type {
+  SegmentKey,
+  PresetName,
+  SettingsConfig,
+  SettingsListItem,
+  SettingsUpdateResult,
+  SegmentMetadata,
+} from "./types.js";
+
+export { DEFAULT_SETTINGS, PRESETS, SEGMENT_METADATA, ZONE_VALUE_OPTIONS } from "./metadata.js";
+
+export {
+  createDefaultSettings,
+  applyPreset,
+  toggleSegment,
+  setSegment,
+  setZone,
+  validateSettings,
+  migrateSettings,
+  updateSetting,
+} from "./domain.js";
+
+export { toSettingsListItems } from "./tui.js";
+
+export {
+  createSettingsStorage,
+  createMemorySettingsStorage,
+  loadSettings,
+  saveSettings,
+} from "./storage.js";
+
+export { createSettingsManager, type SettingsManager } from "./manager.js";

package/extensions/lib/settings/manager.ts

@@ -0,0 +1,58 @@
+import { loadSettings, saveSettings } from "./storage.js";
+import {
+  applyPreset,
+  toggleSegment,
+  setSegment,
+  setZone,
+  createDefaultSettings,
+} from "./domain.js";
+import type { PresetName, SegmentKey, SettingsConfig } from "./types.js";
+import type { Storage } from "../storage/index.js";
+
+export interface SettingsManager {
+  load(): Promise<void>;
+  save(): Promise<void>;
+  getConfig(): SettingsConfig;
+  applyPreset(preset: PresetName): SettingsConfig;
+  toggleSegment(key: SegmentKey): SettingsConfig;
+  setSegment(key: SegmentKey, value: boolean): SettingsConfig;
+  setZone(key: "expert" | "warning", value: number): SettingsConfig;
+}
+
+export function createSettingsManager(storage: Storage): SettingsManager {
+  let config: SettingsConfig = createDefaultSettings();
+
+  return {
+    async load() {
+      config = await loadSettings(storage);
+    },
+
+    async save() {
+      await saveSettings(config, storage);
+    },
+
+    getConfig() {
+      return structuredClone(config);
+    },
+
+    applyPreset(preset) {
+      config = applyPreset(config, preset);
+      return structuredClone(config);
+    },
+
+    toggleSegment(key) {
+      config = toggleSegment(config, key);
+      return structuredClone(config);
+    },
+
+    setSegment(key, value) {
+      config = setSegment(config, key, value);
+      return structuredClone(config);
+    },
+
+    setZone(key, value) {
+      config = setZone(config, key, value);
+      return structuredClone(config);
+    },
+  };
+}

package/extensions/lib/settings/metadata.ts

@@ -0,0 +1,114 @@
+import type { PresetName, SegmentKey, SegmentMetadata, SettingsConfig } from "./types.js";
+
+export const DEFAULT_SETTINGS: SettingsConfig = {
+  version: 1,
+  preset: "standard",
+  segments: {
+    modelThink: true,
+    runtime: true,
+    pwd: true,
+    git: true,
+    contextUsage: true,
+    contextProgress: true,
+    contextPercentage: true,
+    contextNumbers: true,
+    tokens: true,
+    tps: true,
+    cost: true,
+  },
+  contextZones: { expert: 70, warning: 85 },
+};
+
+export const PRESETS: Record<PresetName, Partial<Record<SegmentKey, boolean>>> = {
+  minimal: {
+    modelThink: true,
+    contextUsage: true,
+    contextProgress: true,
+    contextPercentage: false,
+    contextNumbers: true,
+    runtime: false,
+    pwd: false,
+    git: false,
+    tokens: false,
+    tps: false,
+    cost: false,
+  },
+  standard: {
+    modelThink: true,
+    runtime: true,
+    pwd: true,
+    git: true,
+    contextUsage: true,
+    contextProgress: true,
+    contextPercentage: true,
+    contextNumbers: true,
+    tokens: true,
+    tps: false,
+    cost: true,
+  },
+  verbose: {
+    modelThink: true,
+    runtime: true,
+    pwd: true,
+    git: true,
+    contextUsage: true,
+    contextProgress: true,
+    contextPercentage: true,
+    contextNumbers: true,
+    tokens: true,
+    tps: true,
+    cost: true,
+  },
+  performance: {
+    modelThink: true,
+    runtime: false,
+    pwd: false,
+    git: false,
+    contextUsage: true,
+    contextProgress: false,
+    contextPercentage: true,
+    contextNumbers: true,
+    tokens: false,
+    tps: true,
+    cost: true,
+  },
+};
+
+export const SEGMENT_METADATA: SegmentMetadata[] = [
+  {
+    id: "modelThink",
+    label: "Model & Thinking",
+    description: "Show current model and thinking level",
+  },
+  { id: "runtime", label: "Runtime", description: "Show session runtime timer" },
+  { id: "pwd", label: "Working Directory", description: "Show current working directory" },
+  { id: "git", label: "Git Branch & Diff", description: "Show git branch and diff stats" },
+  {
+    id: "contextUsage",
+    label: "Context Usage",
+    description: "Master toggle for the context usage segment",
+  },
+  {
+    id: "contextProgress",
+    label: "  └ Progress Bar",
+    description: "Show the progress bar in context usage",
+  },
+  {
+    id: "contextPercentage",
+    label: "  └ Percentage",
+    description: "Show the percentage in context usage",
+  },
+  {
+    id: "contextNumbers",
+    label: "  └ Used / Total",
+    description: "Show the token count in context usage",
+  },
+  { id: "tokens", label: "Session Tokens", description: "Show total input/output token counts" },
+  { id: "tps", label: "TPS (Tokens/Sec)", description: "Show live and last-turn TPS" },
+  { id: "cost", label: "Cost", description: "Show estimated session cost" },
+];
+
+export const ZONE_VALUE_OPTIONS = {
+  expert: ["60", "65", "70", "75", "80"],
+  warning: ["75", "80", "85", "90", "95"],
+};

package/extensions/lib/settings/storage.ts

@@ -0,0 +1,38 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  createFileBackend,
+  createMemoryBackend,
+  createStorage,
+  type Storage,
+} from "../storage/index.js";
+import { migrateSettings } from "./domain.js";
+import type { SettingsConfig } from "./types.js";
+
+const DEFAULT_DIR = join(homedir(), ".pi", "agent", "observability");
+
+export function createSettingsStorage(options?: { dir?: string }): Storage {
+  const dir = options?.dir ?? DEFAULT_DIR;
+  const backend = createFileBackend({ dir });
+  return createStorage(backend);
+}
+
+export function createMemorySettingsStorage(): Storage {
+  const backend = createMemoryBackend();
+  return createStorage(backend);
+}
+
+export async function loadSettings(storage: Storage): Promise<SettingsConfig> {
+  const store = storage.json<SettingsConfig>("settings", { defaults: undefined });
+  try {
+    const raw = await store.load();
+    return migrateSettings(raw);
+  } catch {
+    return migrateSettings(undefined);
+  }
+}
+
+export async function saveSettings(config: SettingsConfig, storage: Storage): Promise<void> {
+  const store = storage.json<SettingsConfig>("settings");
+  await store.save(config);
+}

package/extensions/lib/settings/tui.ts

@@ -0,0 +1,44 @@
+import { SEGMENT_METADATA, ZONE_VALUE_OPTIONS } from "./metadata.js";
+import type { SettingsConfig, SettingsListItem } from "./types.js";
+
+export function toSettingsListItems(config: SettingsConfig): SettingsListItem[] {
+  const items: SettingsListItem[] = [
+    {
+      id: "preset",
+      label: "Layout Preset",
+      description:
+        "Quick layout presets. Individual segments can still be toggled after applying a preset.",
+      currentValue: config.preset,
+      values: ["minimal", "standard", "verbose", "performance"],
+    },
+  ];
+
+  for (const meta of SEGMENT_METADATA) {
+    items.push({
+      id: meta.id,
+      label: meta.label,
+      description: meta.description,
+      currentValue: config.segments[meta.id] ? "true" : "false",
+      values: ["true", "false"],
+    });
+  }
+
+  items.push(
+    {
+      id: "expertZone",
+      label: "Expert Zone Threshold",
+      description: "Context usage percentage where the bar turns green (0-100)",
+      currentValue: `${config.contextZones.expert}`,
+      values: ZONE_VALUE_OPTIONS.expert,
+    },
+    {
+      id: "warningZone",
+      label: "Warning Zone Threshold",
+      description: "Context usage percentage where the bar turns yellow (0-100)",
+      currentValue: `${config.contextZones.warning}`,
+      values: ZONE_VALUE_OPTIONS.warning,
+    },
+  );
+
+  return items;
+}

package/extensions/lib/settings/types.ts

@@ -0,0 +1,40 @@
+export type SegmentKey =
+  | "modelThink"
+  | "runtime"
+  | "pwd"
+  | "git"
+  | "contextUsage"
+  | "contextProgress"
+  | "contextPercentage"
+  | "contextNumbers"
+  | "tokens"
+  | "tps"
+  | "cost";
+
+export type PresetName = "minimal" | "standard" | "verbose" | "performance";
+
+export interface SettingsConfig {
+  version: number;
+  preset: PresetName;
+  segments: Record<SegmentKey, boolean>;
+  contextZones: { expert: number; warning: number };
+}
+
+export interface SettingsListItem {
+  id: string;
+  label: string;
+  description: string;
+  currentValue: string;
+  values: string[];
+}
+
+export interface SettingsUpdateResult {
+  config: SettingsConfig;
+  derivedUpdates: Array<{ id: string; value: string }>;
+}
+
+export interface SegmentMetadata {
+  id: SegmentKey;
+  label: string;
+  description: string;
+}

package/extensions/lib/storage/file-backend.ts

@@ -0,0 +1,62 @@
+import { mkdir, readFile, rename, writeFile, appendFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { RawBackend } from "./types.js";
+
+export interface FileBackendOptions {
+  dir: string;
+}
+
+export function createFileBackend(options: FileBackendOptions): RawBackend {
+  const { dir } = options;
+  let ensured = false;
+
+  async function ensureDir() {
+    if (ensured) return;
+    await mkdir(dir, { recursive: true });
+    ensured = true;
+  }
+
+  function pathFor(name: string): string {
+    return join(dir, name);
+  }
+
+  return {
+    async read(name) {
+      try {
+        return await readFile(pathFor(name), "utf8");
+      } catch {
+        return undefined;
+      }
+    },
+
+    async write(name, content) {
+      await ensureDir();
+      const target = pathFor(name);
+      const temp = `${target}.tmp`;
+      await writeFile(temp, content, "utf8");
+      await rename(temp, target);
+    },
+
+    async append(name, line) {
+      await ensureDir();
+      await appendFile(pathFor(name), `${line}\n`, "utf8");
+    },
+
+    async readLines(name, options) {
+      const text = await this.read(name);
+      if (!text) return [];
+      const lines = text.split("\n").filter((l) => l.trim());
+      if (options?.last !== undefined && options.last > 0) {
+        return lines.slice(-options.last);
+      }
+      return lines;
+    },
+
+    async trimLines(name, keepLast) {
+      const lines = await this.readLines(name);
+      if (lines.length <= keepLast) return;
+      const kept = lines.slice(-keepLast);
+      await this.write(name, kept.map((l) => `${l}\n`).join(""));
+    },
+  };
+}

package/extensions/lib/storage/index.ts

@@ -0,0 +1,33 @@
+export { createJsonStore } from "./json-store.js";
+export { createJsonlStore } from "./jsonl-store.js";
+export { createFileBackend, type FileBackendOptions } from "./file-backend.js";
+export { createMemoryBackend } from "./memory-backend.js";
+export type { JsonStore, JsonlStore, Storage, RawBackend } from "./types.js";
+
+import { createJsonStore } from "./json-store.js";
+import { createJsonlStore } from "./jsonl-store.js";
+import type { Storage, RawBackend } from "./types.js";
+
+export function createStorage(backend: RawBackend): Storage {
+  return {
+    json<T>(name: string, options?: { defaults?: T }) {
+      return createJsonStore(backend, name, options);
+    },
+    jsonl(name: string) {
+      return createJsonlStore(backend, name);
+    },
+  };
+}
+
+import { createFileBackend } from "./file-backend.js";
+import { createMemoryBackend } from "./memory-backend.js";
+
+export function createFileStorage(options: { dir: string }): Storage {
+  const backend = createFileBackend(options);
+  return createStorage(backend);
+}
+
+export function createMemoryStorage(): Storage {
+  const backend = createMemoryBackend();
+  return createStorage(backend);
+}

package/extensions/lib/storage/json-store.ts

@@ -0,0 +1,32 @@
+import type { JsonStore, RawBackend } from "./types.js";
+
+export function createJsonStore<T>(
+  backend: RawBackend,
+  name: string,
+  options?: { defaults?: T },
+): JsonStore<T> {
+  const fileName = `${name}.json`;
+  const defaults = options?.defaults;
+
+  return {
+    async load(): Promise<T> {
+      const text = await backend.read(fileName);
+      if (text === undefined) {
+        if (defaults !== undefined) return defaults;
+        throw new Error(`Missing file and no defaults for ${fileName}`);
+      }
+      try {
+        return JSON.parse(text) as T;
+      } catch (err) {
+        console.error(`[storage] corrupt JSON in ${fileName}, using defaults:`, err);
+        if (defaults !== undefined) return defaults;
+        throw err;
+      }
+    },
+
+    async save(value: T): Promise<void> {
+      const text = JSON.stringify(value, null, 2);
+      await backend.write(fileName, text);
+    },
+  };
+}

package/extensions/lib/storage/jsonl-store.ts

@@ -0,0 +1,29 @@
+import type { JsonlStore, RawBackend } from "./types.js";
+
+export function createJsonlStore<T>(backend: RawBackend, name: string): JsonlStore<T> {
+  const fileName = `${name}.jsonl`;
+
+  return {
+    async append(value: T): Promise<void> {
+      const line = JSON.stringify(value);
+      await backend.append(fileName, line);
+    },
+
+    async read(options?: { last?: number }): Promise<T[]> {
+      const lines = await backend.readLines(fileName, options);
+      const results: T[] = [];
+      for (const line of lines) {
+        try {
+          results.push(JSON.parse(line) as T);
+        } catch (err) {
+          console.error(`[storage] corrupt JSONL line in ${fileName}, skipping:`, err);
+        }
+      }
+      return results;
+    },
+
+    async trim(options: { keepLast: number }): Promise<void> {
+      await backend.trimLines(fileName, options.keepLast);
+    },
+  };
+}

package/extensions/lib/storage/memory-backend.ts

@@ -0,0 +1,37 @@
+import type { RawBackend } from "./types.js";
+
+export function createMemoryBackend(initial?: Map<string, string>): RawBackend {
+  const store = initial ?? new Map<string, string>();
+
+  return {
+    async read(name) {
+      return store.get(name);
+    },
+
+    async write(name, content) {
+      store.set(name, content);
+    },
+
+    async append(name, line) {
+      const existing = store.get(name) ?? "";
+      store.set(name, `${existing}${line}\n`);
+    },
+
+    async readLines(name, options) {
+      const text = store.get(name);
+      if (!text) return [];
+      const lines = text.split("\n").filter((l) => l.trim());
+      if (options?.last !== undefined && options.last > 0) {
+        return lines.slice(-options.last);
+      }
+      return lines;
+    },
+
+    async trimLines(name, keepLast) {
+      const lines = await this.readLines(name);
+      if (lines.length <= keepLast) return;
+      const kept = lines.slice(-keepLast);
+      store.set(name, kept.map((l) => `${l}\n`).join(""));
+    },
+  };
+}