@rol1n/memory-log 0.0.0-stage → 0.1.1

package/ui/status-controller.ts

@@ -0,0 +1,225 @@
+/**
+ * TUI observability for SRP Observational Memory.
+ */
+
+export type WorkerType = "observer" | "consolidator";
+
+export interface FooterGauges {
+  /** Raw tokens accrued toward the next observer chunk. */
+  nextValue: number;
+  nextMax: number;
+  /** Active pool tokens accrued toward the consolidation threshold. */
+  poolValue: number;
+  poolMax: number;
+  /** Live context-window tokens toward the compaction threshold. */
+  ctxValue: number;
+  ctxMax: number;
+}
+
+interface Theme {
+  fg(color: string, text: string): string;
+  bg?(color: string, text: string): string;
+  bold?(text: string): string;
+}
+
+export interface StatusUI {
+  setStatus(key: string, text: string | undefined): void;
+  setWidget(
+    key: string,
+    content: string[] | undefined,
+    options?: { placement?: "aboveEditor" | "belowEditor" },
+  ): void;
+  theme: Theme;
+}
+
+type WorkerState =
+  | { kind: "running" }
+  | { kind: "done"; delta?: number }
+  | { kind: "error" };
+
+const WIDGET_KEY = "memory-log";
+const LEGACY_WIDGET_KEY = "srp-memory";
+const LEGACY_WORKERS_WIDGET_KEY = "srp-memory-workers";
+const LEGACY_STATUS_KEY = "srp-memory";
+const SPINNER_FRAMES = ["◐", "◓", "◑", "◒"] as const;
+const WORKER_SEP = "   ";
+
+export interface StatusControllerOptions {
+  spinnerIntervalMs?: number;
+  settleMs?: number;
+}
+
+interface WorkerEntry {
+  type: WorkerType;
+  state: WorkerState;
+  settleTimer?: ReturnType<typeof setTimeout>;
+}
+
+export class StatusController {
+  private ui: StatusUI | undefined;
+  private frame = 0;
+  private readonly workers = new Map<string, WorkerEntry>();
+  private spinnerTimer: ReturnType<typeof setInterval> | undefined;
+  private gauges: FooterGauges | undefined;
+  private cost: { costUsd: number; runs: number } | undefined;
+  private readonly spinnerIntervalMs: number;
+  private readonly settleMs: number;
+
+  constructor(options: StatusControllerOptions = {}) {
+    this.spinnerIntervalMs = options.spinnerIntervalMs ?? 120;
+    this.settleMs = options.settleMs ?? 5000;
+  }
+
+  attach(ui: StatusUI): void {
+    this.ui = ui;
+    this.ui.setStatus(LEGACY_STATUS_KEY, undefined);
+    this.ui.setStatus(WIDGET_KEY, undefined);
+    this.ui.setWidget(LEGACY_WORKERS_WIDGET_KEY, undefined);
+    this.ui.setWidget(LEGACY_WIDGET_KEY, undefined);
+    this.renderWidget();
+  }
+
+  detach(): void {
+    this.stopSpinner();
+    for (const entry of this.workers.values()) {
+      if (entry.settleTimer) clearTimeout(entry.settleTimer);
+    }
+    this.workers.clear();
+    this.gauges = undefined;
+    this.cost = undefined;
+    this.ui?.setWidget(WIDGET_KEY, undefined);
+    this.ui?.setWidget(LEGACY_WORKERS_WIDGET_KEY, undefined);
+    this.ui?.setWidget(LEGACY_WIDGET_KEY, undefined);
+    if (this.ui) this.ui.setStatus(LEGACY_STATUS_KEY, undefined);
+    if (this.ui) this.ui.setStatus(WIDGET_KEY, undefined);
+    this.ui = undefined;
+  }
+
+  setGauges(gauges: FooterGauges | undefined): void {
+    this.gauges = gauges;
+    this.renderWidget();
+  }
+
+  setCost(costUsd: number, runs: number): void {
+    this.cost = { costUsd, runs };
+    this.renderWidget();
+  }
+
+  workerStart(type: WorkerType, runId: string): void {
+    if (!this.ui) return;
+    const existing = this.workers.get(runId);
+    if (existing?.settleTimer) clearTimeout(existing.settleTimer);
+    this.workers.set(runId, { type, state: { kind: "running" } });
+    this.startSpinner();
+    this.renderWidget();
+  }
+
+  workerDone(runId: string, delta?: number): void {
+    this.settle(runId, { kind: "done", delta });
+  }
+
+  workerError(runId: string): void {
+    this.settle(runId, { kind: "error" });
+  }
+
+  private settle(runId: string, state: WorkerState): void {
+    if (!this.ui) return;
+    const entry = this.workers.get(runId);
+    if (!entry) return;
+    if (entry.settleTimer) clearTimeout(entry.settleTimer);
+    entry.state = state;
+    this.renderWidget();
+    entry.settleTimer = setTimeout(() => {
+      this.workers.delete(runId);
+      this.renderWidget();
+      if (!this.hasRunningWorker()) this.stopSpinner();
+    }, this.settleMs);
+    (entry.settleTimer as any)?.unref?.();
+    if (!this.hasRunningWorker()) this.stopSpinner();
+  }
+
+  private hasRunningWorker(): boolean {
+    for (const entry of this.workers.values()) {
+      if (entry.state.kind === "running") return true;
+    }
+    return false;
+  }
+
+  private startSpinner(): void {
+    if (this.spinnerTimer) return;
+    this.spinnerTimer = setInterval(() => {
+      this.frame = (this.frame + 1) % SPINNER_FRAMES.length;
+      if (this.hasRunningWorker()) this.renderWidget();
+    }, this.spinnerIntervalMs);
+    (this.spinnerTimer as any)?.unref?.();
+  }
+
+  private stopSpinner(): void {
+    if (!this.spinnerTimer) return;
+    clearInterval(this.spinnerTimer);
+    this.spinnerTimer = undefined;
+  }
+
+  private gaugeBar(value: number, max: number, cells = 6): string {
+    const theme = this.ui!.theme;
+    const frac = max <= 0 ? 0 : Math.max(0, value / max);
+    const filled = Math.min(cells, Math.round(Math.min(1, frac) * cells));
+    const fillColor = frac >= 1 ? "warning" : "dim";
+    return (
+      theme.fg(fillColor, "▕") +
+      theme.fg(fillColor, "█".repeat(filled)) +
+      theme.fg(fillColor, "░".repeat(cells - filled)) +
+      theme.fg(fillColor, "▏")
+    );
+  }
+
+  private renderWorkersLine(): string | undefined {
+    if (this.workers.size === 0) return undefined;
+    const theme = this.ui!.theme;
+    const parts: string[] = [];
+    for (const entry of this.workers.values()) {
+      if (entry.state.kind === "running") {
+        parts.push(`${theme.fg("accent", SPINNER_FRAMES[this.frame])} ${theme.fg("accent", `[${entry.type}]`)}`);
+      } else if (entry.state.kind === "error") {
+        parts.push(`${theme.fg("error", "✗")} ${theme.fg("muted", `[${entry.type}]`)}`);
+      } else {
+        const delta =
+          entry.state.delta && entry.state.delta > 0
+            ? ` ${theme.fg("success", `+${entry.state.delta}`)}`
+            : "";
+        parts.push(`${theme.fg("success", "✓")} ${theme.fg("muted", `[${entry.type}]`)}${delta}`);
+      }
+    }
+    return parts.length > 0 ? parts.join(WORKER_SEP) : undefined;
+  }
+
+  private renderMemLine(): string {
+    const theme = this.ui?.theme;
+    if (!theme) return "memory-log";
+    const base = `${theme.fg("success", "● mem")}`;
+    const g = this.gauges;
+    if (!g) return base;
+    const next = `${theme.fg("muted", "O")}${this.gaugeBar(g.nextValue, g.nextMax)}`;
+    const pool = `${theme.fg("muted", "C")}${this.gaugeBar(g.poolValue, g.poolMax)}`;
+    const ctx = `${theme.fg("muted", "X")}${this.gaugeBar(g.ctxValue, g.ctxMax)}`;
+    const cost = this.cost && this.cost.costUsd > 0 ? ` ${theme.fg("dim", `$${this.cost.costUsd.toFixed(3)}`)}` : "";
+    return `${base} ${next} ${pool} ${ctx}${cost}`;
+  }
+
+  private renderWidget(): void {
+    const ui = this.ui;
+    if (!ui) return;
+
+    const lines: string[] = [];
+    const workersLine = this.renderWorkersLine();
+    if (workersLine) {
+      lines.push(workersLine);
+    }
+    const memLine = this.renderMemLine();
+    if (memLine) {
+      lines.push(memLine);
+    }
+
+    ui.setWidget(WIDGET_KEY, lines.length > 0 ? lines : undefined, { placement: "aboveEditor" });
+  }
+}

package/ui/timeline.ts

@@ -0,0 +1,103 @@
+import type { Config } from "../config.ts";
+import {
+  entryIndexById,
+  foldLedger,
+  isObservationsRecordedEntry,
+  rawTokensAfterIndex,
+  rawTokensSinceObservationCoverage,
+  type Entry,
+} from "../ledger/index.ts";
+
+/** Glyphs for the timeline strip. */
+const GLYPH = {
+  consolidated: "▓", // observations promoted to .memory (long-term)
+  partial: "▚",      // chunk straddling the pool-target boundary (some obs promoted)
+  pool: "▒",         // observed, still in the short-term buffer
+  raw: "░",          // raw history not yet distilled into observations
+  cut: "┊",          // compaction cutoff (verbatim tail began here)
+  tip: "▶",          // live branch tip
+} as const;
+
+/** A committed observation chunk, in branch order. */
+type Chunk = { coversUpToIndex: number; timestamps: string[] };
+
+function fmtK(tokens: number): string {
+  if (tokens < 1000) return `${tokens}`;
+  return `${(tokens / 1000).toFixed(1)}k`;
+}
+
+function collectChunks(branch: Entry[]): Chunk[] {
+  const indexById = entryIndexById(branch);
+  const chunks: Chunk[] = [];
+  for (const entry of branch) {
+    if (!isObservationsRecordedEntry(entry)) continue;
+    const coversUpToIndex = indexById.get(entry.data.coversUpToId);
+    if (coversUpToIndex === undefined) continue;
+    chunks.push({ coversUpToIndex, timestamps: entry.data.observations.map((o) => o.timestamp) });
+  }
+  return chunks;
+}
+
+/** Branch indices of every compaction entry's `firstKeptEntryId` (the verbatim-tail cutoffs). */
+function compactionCutIndices(branch: Entry[]): number[] {
+  const indexById = entryIndexById(branch);
+  const cuts: number[] = [];
+  for (const entry of branch) {
+    if (entry.type !== "compaction") continue;
+    const idx = entry.firstKeptEntryId ? indexById.get(entry.firstKeptEntryId) : undefined;
+    if (idx !== undefined) cuts.push(idx);
+  }
+  return cuts;
+}
+
+function chunkGlyph(chunk: Chunk, dropped: Set<string>): string {
+  let droppedCount = 0;
+  for (const ts of chunk.timestamps) if (dropped.has(ts)) droppedCount++;
+  if (droppedCount === 0) return GLYPH.pool;
+  if (droppedCount === chunk.timestamps.length) return GLYPH.consolidated;
+  return GLYPH.partial;
+}
+
+function wrap(cells: string[], width: number): string {
+  if (cells.length === 0) return "";
+  const rows: string[] = [];
+  for (let i = 0; i < cells.length; i += width) rows.push(cells.slice(i, i + width).join(""));
+  return rows.join("\n");
+}
+
+/**
+ * Render the full session as a horizontal strip.
+ */
+export function renderTimeline(branch: Entry[], config: Config, width = 60): string {
+  const folded = foldLedger(branch);
+  const dropped = folded.droppedObservationTimestamps;
+  const chunks = collectChunks(branch);
+
+  const cells: string[] = chunks.map((chunk) => chunkGlyph(chunk, dropped));
+  const tailTokens = rawTokensSinceObservationCoverage(branch);
+  const tailCells = tailTokens > 0 ? Math.ceil(tailTokens / config.chunkTokens) : 0;
+  for (let i = 0; i < tailCells; i++) cells.push(GLYPH.raw);
+
+  const cutPositions = compactionCutIndices(branch)
+    .map((cutIdx) => {
+      let pos = 0;
+      for (const chunk of chunks) if (chunk.coversUpToIndex < cutIdx) pos++;
+      return Math.min(pos, cells.length);
+    })
+    .sort((a, b) => b - a);
+  for (const pos of cutPositions) cells.splice(pos, 0, GLYPH.cut);
+
+  const consolidatedChunks = chunks.filter((c) => chunkGlyph(c, dropped) === GLYPH.consolidated).length;
+  const poolChunks = chunks.filter((c) => chunkGlyph(c, dropped) === GLYPH.pool).length;
+  const rawTotal = rawTokensAfterIndex(branch, -1);
+  const compactions = cutPositions.length;
+
+  const strip = cells.length > 0 ? `${wrap(cells, width)}${GLYPH.tip}` : "(timeline empty)";
+
+  return [
+    `memory-log timeline · 1 cell ≈ ${fmtK(config.chunkTokens)} tok · cumulative ${fmtK(rawTotal)} raw · ${compactions} compaction${compactions === 1 ? "" : "s"}`,
+    strip,
+    ``,
+    `  ${GLYPH.consolidated} .memory (${consolidatedChunks})   ${GLYPH.pool} pool (${poolChunks})   ${GLYPH.raw} raw   ${GLYPH.cut} compaction cut   ${GLYPH.tip} tip`,
+  ].join("\n");
+}