@mrdrmccoy/xerj-opencode-plugin 0.0.0-stage → 0.4.1

package/src/stats/counters.ts

@@ -0,0 +1,55 @@
+// Per-process counters for events the plugin can observe directly. They reset
+// when the server restarts, so the UI labels them as this server's lifetime.
+// Index-run totals live in the corpus snapshots (persisted), not here.
+
+export interface CounterSnapshot {
+  readonly rpcCalls: number;
+  readonly injectedTurns: number;
+  readonly nodeSpawns: number;
+  readonly http429: number;
+  readonly indexRuns: number;
+}
+
+/** Counts events without changing them; callers never branch on a counter. */
+export class Counters {
+  private rpc = 0;
+  private injected = 0;
+  private spawns = 0;
+  private limited = 0;
+  private indexed = 0;
+
+  /** A TUI poll or any other RPC call reached the server part. */
+  noteRpc(): void {
+    this.rpc += 1;
+  }
+
+  /** A retrieved block was added to a prompt. */
+  noteInjection(): void {
+    this.injected += 1;
+  }
+
+  /** A node process was started rather than attached to. */
+  noteSpawn(): void {
+    this.spawns += 1;
+  }
+
+  /** The node answered 429; autoindex waits these out on its own. */
+  note429(): void {
+    this.limited += 1;
+  }
+
+  /** One index pass finished, in any corpus. */
+  noteIndexRun(): void {
+    this.indexed += 1;
+  }
+
+  snapshot(): CounterSnapshot {
+    return {
+      rpcCalls: this.rpc,
+      injectedTurns: this.injected,
+      nodeSpawns: this.spawns,
+      http429: this.limited,
+      indexRuns: this.indexed,
+    };
+  }
+}

package/src/stats/ledger.ts

@@ -0,0 +1,344 @@
+// Retrieval accounting. Everything here is measured: bytes actually handed to
+// the model, the size of each cited file, and whether the model read that file
+// anyway. The last point is what keeps "tokens saved" from being fiction: a
+// file the model read in full contributes nothing, even if a passage from it
+// was cited first.
+
+import { stat } from "node:fs/promises";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import type { KeyValueStorage, Logger } from "../log.ts";
+
+export interface CitedFile {
+  readonly path: string;
+  readonly citations: number;
+  readonly bytes: number;
+}
+
+export interface LedgerSnapshot {
+  readonly queries: number;
+  readonly hits: number;
+  readonly hitRate: number;
+  readonly bytesReturned: number;
+  readonly baselineBytes: number;
+  readonly filesCited: number;
+  readonly filesRead: number;
+  readonly bytesRead: number;
+  readonly savedBytes: number;
+  readonly tokensSaved: number;
+  readonly topFiles: ReadonlyArray<CitedFile>;
+}
+
+export interface LedgerOptions {
+  readonly storage: KeyValueStorage;
+  readonly projectRoot: string;
+  readonly bytesPerToken: number;
+  readonly maxBaselineBytes: number;
+  readonly logger: Logger;
+}
+
+interface SessionState {
+  readonly cited: Map<string, number>;
+  readonly citations: Map<string, number>;
+  /** Bytes the model already read from a cited file. */
+  readonly read: Map<string, number>;
+  queries: number;
+  hits: number;
+  returned: number;
+}
+
+interface LifetimeState {
+  queries: number;
+  hits: number;
+  returned: number;
+  bytesRead: number;
+  readonly cited: Map<string, number>;
+  readonly citations: Map<string, number>;
+  readonly read: Map<string, number>;
+}
+
+const STORAGE_KEY = "stats/lifetime";
+const MAX_TRACKED_FILES = 5000;
+const FLUSH_DELAY_MS = 2_000;
+
+export class Ledger {
+  private readonly sessions = new Map<string, SessionState>();
+  private readonly sizes = new Map<string, number>();
+  private lifetime: LifetimeState = {
+    queries: 0,
+    hits: 0,
+    returned: 0,
+    bytesRead: 0,
+    cited: new Map(),
+    citations: new Map(),
+    read: new Map(),
+  };
+  private loadPromise: Promise<void> | null = null;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(private readonly options: LedgerOptions) {
+    // Warm the persisted counters so the first status after a restart is real.
+    void this.load();
+  }
+
+  async recordQuery(
+    sessionID: string,
+    paths: ReadonlyArray<string>,
+    bytes: number,
+    hits: number,
+  ): Promise<void> {
+    await this.load();
+    const session = this.session(sessionID);
+
+    session.queries += 1;
+    session.returned += bytes;
+    this.lifetime.queries += 1;
+    this.lifetime.returned += bytes;
+
+    if (hits > 0) {
+      session.hits += 1;
+      this.lifetime.hits += 1;
+    }
+
+    for (const path of new Set(paths)) {
+      session.citations.set(path, (session.citations.get(path) ?? 0) + 1);
+      this.lifetime.citations.set(
+        path,
+        (this.lifetime.citations.get(path) ?? 0) + 1,
+      );
+
+      if (!session.cited.has(path)) {
+        const size = await this.fileSize(path);
+        if (size === null) continue;
+        session.cited.set(path, size);
+        this.lifetime.cited.set(path, size);
+      }
+    }
+
+    this.trim();
+    this.scheduleFlush();
+  }
+
+  async recordRead(sessionID: string, filePath: string, bytes: number): Promise<void> {
+    await this.load();
+    const path = this.relative(filePath);
+    if (path === null) return;
+
+    // A read with no measured size counts as the whole file.
+    const amount = Number.isFinite(bytes) && bytes > 0 ? bytes : Number.POSITIVE_INFINITY;
+    const session = this.session(sessionID);
+    bumpRead(session.read, path, amount);
+    bumpRead(this.lifetime.read, path, amount);
+
+    if (Number.isFinite(amount)) {
+      this.lifetime.bytesRead += amount;
+    }
+
+    this.scheduleFlush();
+  }
+
+  snapshot(sessionID?: string): LedgerSnapshot {
+    const session = sessionID ? this.sessions.get(sessionID) : undefined;
+    const cited = session?.cited ?? this.lifetime.cited;
+    const citations = session?.citations ?? this.lifetime.citations;
+    const read = session?.read ?? this.lifetime.read;
+    const queries = session?.queries ?? this.lifetime.queries;
+    const hits = session?.hits ?? this.lifetime.hits;
+    const returned = session?.returned ?? this.lifetime.returned;
+
+    let baseline = 0;
+    let filesCited = 0;
+    for (const [path, size] of cited) {
+      filesCited += 1;
+      const alreadyRead = read.get(path) ?? 0;
+      baseline += Math.max(0, size - alreadyRead);
+    }
+
+    const saved = Math.max(0, baseline - returned);
+    return {
+      queries,
+      hits,
+      hitRate: queries === 0 ? 0 : hits / queries,
+      bytesReturned: returned,
+      baselineBytes: baseline,
+      filesCited,
+      filesRead: read.size,
+      bytesRead: this.lifetime.bytesRead,
+      savedBytes: saved,
+      tokensSaved: Math.round(saved / this.options.bytesPerToken),
+      topFiles: topCited(citations, cited),
+    };
+  }
+
+  async flush(): Promise<void> {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    await this.save();
+  }
+
+  private load(): Promise<void> {
+    this.loadPromise ??= this.loadFromStorage();
+    return this.loadPromise;
+  }
+
+  private async loadFromStorage(): Promise<void> {
+    const stored = await this.options.storage.get(STORAGE_KEY).catch(() => undefined);
+    if (typeof stored !== "object" || stored === null) return;
+
+    const record = stored as Record<string, unknown>;
+    this.lifetime = {
+      queries: numberOr(record.queries, 0),
+      hits: numberOr(record.hits, 0),
+      returned: numberOr(record.returned, 0),
+      bytesRead: numberOr(record.bytesRead, 0),
+      cited: fileMap(record.cited),
+      citations: countMap(record.citations),
+      read: fileMap(record.read),
+    };
+  }
+
+  private session(sessionID: string): SessionState {
+    let session = this.sessions.get(sessionID);
+    if (!session) {
+      session = {
+        cited: new Map(),
+        citations: new Map(),
+        read: new Map(),
+        queries: 0,
+        hits: 0,
+        returned: 0,
+      };
+      this.sessions.set(sessionID, session);
+    }
+    return session;
+  }
+
+  private async fileSize(path: string): Promise<number | null> {
+    const cached = this.sizes.get(path);
+    if (cached !== undefined) return cached;
+
+    const absolute = this.absolute(path);
+    if (absolute === null) return null;
+
+    const info = await stat(absolute).catch(() => null);
+    if (!info?.isFile()) return null;
+
+    const size = Math.min(info.size, this.options.maxBaselineBytes);
+    this.sizes.set(path, size);
+    return size;
+  }
+
+  private absolute(path: string): string | null {
+    const root = resolve(this.options.projectRoot);
+    const absolute = isAbsolute(path) ? resolve(path) : resolve(join(root, path));
+    if (absolute !== root && !absolute.startsWith(root + sep)) return null;
+    return absolute;
+  }
+
+  private relative(path: string): string | null {
+    const absolute = this.absolute(path);
+    if (absolute === null) return null;
+    const root = resolve(this.options.projectRoot);
+    return absolute === root ? "" : absolute.slice(root.length + 1);
+  }
+
+  /** Keeps the tracked set bounded without losing recent evidence. */
+  private trim(): void {
+    while (this.lifetime.cited.size > MAX_TRACKED_FILES) {
+      const oldest = this.lifetime.cited.keys().next().value;
+      if (oldest === undefined) break;
+      this.lifetime.cited.delete(oldest);
+    }
+    while (this.lifetime.citations.size > MAX_TRACKED_FILES) {
+      const oldest = this.lifetime.citations.keys().next().value;
+      if (oldest === undefined) break;
+      this.lifetime.citations.delete(oldest);
+    }
+    while (this.lifetime.read.size > MAX_TRACKED_FILES) {
+      const oldest = this.lifetime.read.keys().next().value;
+      if (oldest === undefined) break;
+      this.lifetime.read.delete(oldest);
+    }
+  }
+
+  private scheduleFlush(): void {
+    if (this.timer) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.save();
+    }, FLUSH_DELAY_MS);
+  }
+
+  private async save(): Promise<void> {
+    const payload = {
+      queries: this.lifetime.queries,
+      hits: this.lifetime.hits,
+      returned: this.lifetime.returned,
+      bytesRead: this.lifetime.bytesRead,
+      cited: [...this.lifetime.cited].slice(-MAX_TRACKED_FILES),
+      citations: [...this.lifetime.citations].slice(-MAX_TRACKED_FILES),
+      // Infinity is not JSON; -1 means "the whole file was read".
+      read: [...this.lifetime.read]
+        .slice(-MAX_TRACKED_FILES)
+        .map(([path, amount]) => [path, Number.isFinite(amount) ? amount : -1]),
+    };
+
+    await this.options.storage.set(STORAGE_KEY, payload as never).catch((error: unknown) => {
+      this.options.logger.debug("could not persist stats", String(error));
+    });
+  }
+}
+
+function numberOr(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function fileMap(value: unknown): Map<string, number> {
+  const map = new Map<string, number>();
+  if (!Array.isArray(value)) return map;
+
+  for (const entry of value) {
+    if (!Array.isArray(entry) || entry.length !== 2) continue;
+    const [path, size] = entry;
+    if (typeof path === "string" && typeof size === "number") {
+      map.set(path, size < 0 ? Number.POSITIVE_INFINITY : size);
+    }
+  }
+  return map;
+}
+
+function countMap(value: unknown): Map<string, number> {
+  const map = new Map<string, number>();
+  if (!Array.isArray(value)) return map;
+
+  for (const entry of value) {
+    if (!Array.isArray(entry) || entry.length !== 2) continue;
+    const [path, count] = entry;
+    if (typeof path === "string" && typeof count === "number" && count > 0) {
+      map.set(path, count);
+    }
+  }
+  return map;
+}
+
+const TOP_FILES = 5;
+
+function topCited(
+  citations: ReadonlyMap<string, number>,
+  cited: ReadonlyMap<string, number>,
+): CitedFile[] {
+  return [...citations.entries()]
+    .map(([path, count]) => ({ path, citations: count, bytes: cited.get(path) ?? 0 }))
+    .sort((left, right) => right.citations - left.citations || left.path.localeCompare(right.path))
+    .slice(0, TOP_FILES);
+}
+
+function bumpRead(map: Map<string, number>, path: string, amount: number): void {
+  if (map.get(path) === Number.POSITIVE_INFINITY) return;
+  if (amount === Number.POSITIVE_INFINITY) {
+    map.set(path, amount);
+    return;
+  }
+  map.set(path, (map.get(path) ?? 0) + amount);
+}

package/src/telemetry/anomaly.ts

@@ -0,0 +1,211 @@
+// On-demand anomaly scoring. XERJ has no datafeed: creating a detector and
+// scoring it returns the whole timeline, and only the flagged buckets are
+// formatted for the model.
+//
+// Verified against v1.0.0-rc.100: PUT creates or replaces a detector;
+// POST /_score accepts `anomaly_threshold`; the response carries
+// `anomaly_count` and an `anomalies` array with timestamp, actual, expected,
+// z-score, and score.
+
+import { createHash } from "node:crypto";
+import type { Logger } from "../log.ts";
+import type { XerjClient } from "../node/client.ts";
+
+export type AnomalyFunction = "count" | "mean" | "min" | "max" | "sum";
+
+const FUNCTIONS: ReadonlySet<string> = new Set(["count", "mean", "min", "max", "sum"]);
+const DEFAULT_TIME_FIELD = "@timestamp";
+const DEFAULT_BUCKET_SPAN = "1h";
+const DEFAULT_THRESHOLD = 3;
+const MAX_POINTS = 10;
+
+export interface AnomalyRequest {
+  readonly index: string;
+  readonly timeField?: string;
+  readonly function?: string;
+  readonly field?: string;
+  readonly bucketSpan?: string;
+  readonly threshold?: number;
+}
+
+export interface AnomalyPoint {
+  readonly timestamp: string;
+  readonly actual: number | null;
+  readonly expected: number | null;
+  readonly zScore: number | null;
+  readonly score: number | null;
+}
+
+export interface AnomalyResult {
+  readonly detector: string;
+  readonly index: string;
+  readonly anomalyCount: number;
+  readonly buckets: number;
+  readonly threshold: number;
+  readonly points: ReadonlyArray<AnomalyPoint>;
+}
+
+export class AnomalyService {
+  constructor(
+    private readonly client: XerjClient,
+    private readonly logger: Logger,
+  ) {}
+
+  async score(request: AnomalyRequest): Promise<AnomalyResult> {
+    const index = request.index.trim();
+    if (index.length === 0) throw new Error("anomaly index is required");
+
+    const fn = normalizeFunction(request.function);
+    if (fn !== "count" && (request.field ?? "").trim().length === 0) {
+      throw new Error(`anomaly function ${fn} needs a field`);
+    }
+
+    const timeField = request.timeField?.trim() || DEFAULT_TIME_FIELD;
+    const bucketSpan = request.bucketSpan?.trim() || DEFAULT_BUCKET_SPAN;
+    const threshold = normalizeThreshold(request.threshold);
+    const detector = detectorId({ index, timeField, fn, field: request.field, bucketSpan });
+
+    const config = {
+      source_index: index,
+      time_field: timeField,
+      function: fn,
+      ...(fn === "count" ? {} : { field: request.field }),
+      bucket_span: bucketSpan,
+      anomaly_threshold: threshold,
+      description: `opencode-xerj anomaly detector for ${index}`,
+    };
+
+    await this.client.put(
+      `/_ml/anomaly_detectors/${encodeURIComponent(detector)}`,
+      config,
+      "could not create the anomaly detector",
+    );
+
+    const response = await this.client.post(
+      `/_ml/anomaly_detectors/${encodeURIComponent(detector)}/_score`,
+      { anomaly_threshold: threshold },
+      "anomaly scoring failed",
+    );
+
+    this.logger.debug("scored an anomaly detector", { detector, index });
+    return parseAnomalyScore(detector, index, response, threshold);
+  }
+}
+
+/** Stable per configuration so repeated calls replace one detector. */
+export function detectorId(input: {
+  index: string;
+  timeField: string;
+  fn: string;
+  field?: string;
+  bucketSpan: string;
+}): string {
+  const parts = [
+    input.index,
+    input.timeField,
+    input.fn,
+    input.field ?? "",
+    input.bucketSpan,
+  ];
+  const key = parts.join("|");
+  return `xop-${createHash("sha256").update(key).digest("hex").slice(0, 12)}`;
+}
+
+export function parseAnomalyScore(
+  detector: string,
+  index: string,
+  response: unknown,
+  fallbackThreshold: number,
+): AnomalyResult {
+  if (!isRecord(response)) throw new Error("malformed anomaly response");
+
+  const raw = Array.isArray(response.anomalies) ? response.anomalies : [];
+  const points = raw.flatMap((entry): AnomalyPoint[] => {
+    if (!isRecord(entry)) return [];
+    const timestamp = stringValue(entry.timestamp_iso) ?? stringValue(entry.timestamp);
+    if (timestamp === null) return [];
+
+    return [
+      {
+        timestamp,
+        actual: numberValue(entry.actual),
+        expected: numberValue(entry.expected),
+        zScore: numberValue(entry.z_score),
+        score: numberValue(entry.anomaly_score),
+      },
+    ];
+  });
+
+  return {
+    detector,
+    index,
+    anomalyCount: numberValue(response.anomaly_count) ?? points.length,
+    buckets: numberValue(response.bucket_count) ?? numberValue(response.buckets) ?? 0,
+    threshold: numberValue(response.anomaly_threshold) ?? fallbackThreshold,
+    points,
+  };
+}
+
+export function formatAnomalies(result: AnomalyResult): string {
+  if (result.anomalyCount === 0) {
+    return `No anomalies in ${describeBuckets(result.buckets)} (threshold ${result.threshold}).`;
+  }
+
+  const summary =
+    `${result.anomalyCount} ` +
+    `${result.anomalyCount === 1 ? "anomaly" : "anomalies"} in ` +
+    `${describeBuckets(result.buckets)} (threshold ${result.threshold}).`;
+  const lines = [summary, `detector ${result.detector} over ${result.index}`];
+
+  for (const point of result.points.slice(0, MAX_POINTS)) {
+    lines.push(
+      [
+        point.timestamp,
+        `actual=${formatNumber(point.actual)}`,
+        `expected=${formatNumber(point.expected)}`,
+        `z=${formatNumber(point.zScore, 1)}`,
+        `score=${formatNumber(point.score, 1)}`,
+      ].join("  "),
+    );
+  }
+
+  if (result.points.length > MAX_POINTS) {
+    lines.push(`… ${result.points.length - MAX_POINTS} more`);
+  }
+  return lines.join("\n");
+}
+
+function describeBuckets(buckets: number): string {
+  return buckets > 0 ? `${buckets} buckets` : "the scored timeline";
+}
+
+function normalizeFunction(value: string | undefined): AnomalyFunction {
+  const fn = (value ?? "count").trim().toLowerCase();
+  if (!FUNCTIONS.has(fn)) {
+    throw new Error(`anomaly function must be one of ${[...FUNCTIONS].join(", ")}`);
+  }
+  return fn as AnomalyFunction;
+}
+
+function normalizeThreshold(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value) || value <= 0) {
+    return DEFAULT_THRESHOLD;
+  }
+  return value;
+}
+
+function formatNumber(value: number | null, digits = 2): string {
+  return value === null ? "-" : value.toFixed(digits);
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function numberValue(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}