@evoclock/pi-agentic-driver 0.9.2 → 0.9.3

package/janus/janus/audit.ts

@@ -0,0 +1,213 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Audit log (§5, M9 + round-2 retention rule): append-only local log of
+// request id, timestamps, question NAMES (non-sensitive identifiers, never
+// question text or state contents), verdict probabilities, and token usage.
+// 90-day default retention (config-adjustable), size-capped with
+// oldest-first rotation.
+//
+// Retention (review fix #7): enforced for the ACTIVE file as well as rotated
+// files. On start, after each rotation, and on a periodic sweep, records
+// older than the retention window are purged from the active file by
+// rewriting it without them, and rotated files older than the window are
+// deleted. Records older than retention never survive indefinitely.
+
+import {
+  closeSync,
+  existsSync,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  readSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeSync,
+} from "node:fs";
+import { dirname } from "node:path";
+
+export interface AuditEntry {
+  requestId: string;
+  timestamp: string;
+  event: "evaluate" | "evaluate_result" | "evaluate_error";
+  /** Non-sensitive question identifiers — never question text. */
+  questionNames: string[];
+  verdictProbabilities?: Record<string, number>;
+  tokenUsage?: { inputTokens?: number | undefined; outputTokens?: number | undefined; totalTokens?: number | undefined };
+  errorCode?: string;
+  durationMs?: number;
+  coalesced?: boolean;
+  /** How many provider attempts this request consumed (1 = no failover). */
+  providerAttempts?: number;
+  /** Provider id that produced the result (or last attempted). */
+  provider?: string;
+}
+
+const MAX_ROTATED_FILES = 5;
+/** How often the active-file retention sweep runs while the log is open. */
+const RETENTION_SWEEP_INTERVAL_MS = 60 * 60 * 1000;
+
+function entryTimestampMs(line: string): number | undefined {
+  try {
+    const parsed = JSON.parse(line) as { timestamp?: unknown };
+    if (typeof parsed.timestamp !== "string") return undefined;
+    const ms = Date.parse(parsed.timestamp);
+    return Number.isFinite(ms) ? ms : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export class AuditLog {
+  private fd: number | null = null;
+  private readonly activePath: string;
+  private lastSweepAt = 0;
+
+  constructor(
+    private readonly basePath: string,
+    private readonly maxBytes: number,
+    private readonly retentionDays: number,
+    private readonly now: () => Date = () => new Date(),
+  ) {
+    this.activePath = basePath === "stdout" ? "stdout" : `${basePath}.jsonl`;
+  }
+
+  /** Open (or reopen) the log and apply retention. Call once at startup. */
+  start(): void {
+    if (this.activePath === "stdout") return;
+    mkdirSync(dirname(this.activePath), { recursive: true });
+    this.applyRetention();
+    this.openFd();
+  }
+
+  stop(): void {
+    if (this.fd !== null) {
+      closeSync(this.fd);
+      this.fd = null;
+    }
+  }
+
+  private openFd(): void {
+    this.fd = openSync(this.activePath, "a");
+  }
+
+  /**
+   * Purge records older than the retention window from the ACTIVE file by
+   * rewriting it without them. Rotated-file deletion is handled separately
+   * by mtime in applyRetention(). This guarantees active-file records do not
+   * survive past retention (review fix #7).
+   */
+  private sweepActiveFile(): void {
+    if (this.activePath === "stdout") return;
+    const cutoff = this.now().getTime() - this.retentionDays * 24 * 60 * 60 * 1000;
+
+    let size = 0;
+    try {
+      size = statSync(this.activePath).size;
+    } catch {
+      return;
+    }
+    if (size === 0) return;
+
+    // Read the whole active file (bounded by maxBytes + slack), filter, and
+    // rewrite in place if anything expired.
+    let raw: string;
+    const fd = openSync(this.activePath, "r");
+    try {
+      const buffer = Buffer.alloc(size);
+      const read = readSync(fd, buffer, 0, size, 0);
+      raw = buffer.toString("utf8", 0, read);
+    } finally {
+      closeSync(fd);
+    }
+
+    const lines = raw.split("\n");
+    const kept: string[] = [];
+    for (const line of lines) {
+      if (line.length === 0) continue;
+      const ts = entryTimestampMs(line);
+      if (ts === undefined || ts >= cutoff) kept.push(line);
+    }
+    if (kept.length === lines.filter((l) => l.length > 0).length) return; // nothing expired
+
+    const replacement = `${kept.join("\n")}\n`;
+    // Rewrite via a temp file + rename for atomicity, then reopen for append.
+    const tempPath = `${this.activePath}.sweep`;
+    const tempFd = openSync(tempPath, "w");
+    try {
+      writeSync(tempFd, replacement);
+    } finally {
+      closeSync(tempFd);
+    }
+    if (this.fd !== null) {
+      closeSync(this.fd);
+      this.fd = null;
+    }
+    renameSync(tempPath, this.activePath);
+    this.openFd();
+  }
+
+  private applyRetention(): void {
+    const cutoff = this.now().getTime() - this.retentionDays * 24 * 60 * 60 * 1000;
+    for (let i = 1; i <= MAX_ROTATED_FILES; i += 1) {
+      const rotated = `${this.activePath}.${i}`;
+      if (!existsSync(rotated)) continue;
+      try {
+        if (statSync(rotated).mtimeMs < cutoff) unlinkSync(rotated);
+      } catch {
+        // A missing file mid-scan is fine; retention is best-effort.
+      }
+    }
+    this.sweepActiveFile();
+    this.lastSweepAt = this.now().getTime();
+  }
+
+  private rotateIfNeeded(): void {
+    if (this.activePath === "stdout" || this.fd === null) return;
+    let size = 0;
+    try {
+      size = fstatSync(this.fd).size;
+    } catch {
+      return;
+    }
+    if (size < this.maxBytes) return;
+
+    // Oldest-first rotation: .4→.5, .3→.4, … .1→.2, active→.1.
+    for (let i = MAX_ROTATED_FILES - 1; i >= 1; i -= 1) {
+      const from = `${this.activePath}.${i}`;
+      const to = `${this.activePath}.${i + 1}`;
+      if (existsSync(from)) {
+        try {
+          unlinkSync(to);
+        } catch {
+          /* first shift may have no target */
+        }
+        renameSync(from, to);
+      }
+    }
+    closeSync(this.fd);
+    this.fd = null;
+    renameSync(this.activePath, `${this.activePath}.1`);
+    this.applyRetention();
+    this.openFd();
+  }
+
+  append(entry: AuditEntry): void {
+    const line = `${JSON.stringify(entry)}\n`;
+    if (this.activePath === "stdout") {
+      process.stdout.write(line);
+      return;
+    }
+    if (this.fd === null) this.openFd();
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    writeSync(this.fd!, line);
+    this.rotateIfNeeded();
+    // Periodic active-file retention sweep (review fix #7).
+    const nowMs = this.now().getTime();
+    if (nowMs - this.lastSweepAt >= RETENTION_SWEEP_INTERVAL_MS) {
+      this.sweepActiveFile();
+      this.lastSweepAt = nowMs;
+    }
+  }
+}

package/janus/janus/budget.ts

@@ -0,0 +1,101 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Budget accounting (§2, §5): the authoritative request budget is 30k tokens
+// for state + questions + framing. Anything exceeding the budget after
+// shaping is rejected with state_too_large — never truncated silently.
+//
+// Conservative token bound (review fix #3): the estimate is byte-based with
+// an explicit worst-case floor of 1 token per 2 UTF-8 bytes. This dominates
+// chars/4 for every encoding shape:
+//   - ASCII prose:        1 byte/char  → 2 bytes/token  (≥ chars/4)
+//   - CJK / emoji:        3–4 bytes/char → 1.5–2 bytes/token (chars/4 would
+//     undercount a 4-byte emoji as 0.25 tokens; this bound charges ≥ 2)
+//   - dense/base64 JSON:  1 byte/char → 2 bytes/token (chars/4 undercounts
+//     by 2×; dense JSON tokenizes at ~1–2 bytes/token in practice)
+// The bound can over-reject (e.g. very compressive scripts) but never
+// materially undercounts. It runs BEFORE any external call so oversized
+// requests never reach a provider.
+
+import { createHash } from "node:crypto";
+import { stateTooLarge } from "./errors.js";
+import type { EnforcedQuestion } from "./schema.js";
+
+/** Conservative worst-case bytes per token (finding #3): 1 token per 2 UTF-8 bytes. */
+export const BYTES_PER_TOKEN_CONSERVATIVE = 2;
+
+/** Canonical JSON with object keys sorted (stable digests). */
+export function canonicalJson(value: unknown): string {
+  return JSON.stringify(canonicalize(value));
+}
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value !== null && typeof value === "object") {
+    const sorted: Record<string, unknown> = {};
+    for (const k of Object.keys(value).sort()) {
+      sorted[k] = canonicalize((value as Record<string, unknown>)[k]);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+/**
+ * Conservative token estimate for a string: UTF-8 bytes / 2, rounded up.
+ * Dominates chars/4 for CJK, emoji, and dense encoded content; can
+ * over-reject but never materially undercounts.
+ */
+export function estimateStringTokens(text: string): number {
+  return Math.ceil(Buffer.byteLength(text, "utf8") / BYTES_PER_TOKEN_CONSERVATIVE);
+}
+
+export interface RequestSize {
+  estimatedTokens: number;
+  stateBytes: number;
+}
+
+export function estimateRequestTokens(
+  state: unknown,
+  questions: readonly EnforcedQuestion[],
+  budgetTokens: number,
+  maxStateBytes: number,
+): RequestSize {
+  const stateJson = canonicalJson(state);
+  const stateBytes = Buffer.byteLength(stateJson, "utf8");
+  if (stateBytes > maxStateBytes) {
+    throw stateTooLarge(
+      `state is ${stateBytes} bytes; the hard byte ceiling is ${maxStateBytes} — shape to digests/summaries and retry`,
+      { stateBytes, maxStateBytes },
+    );
+  }
+
+  let tokens = estimateStringTokens(stateJson);
+  for (const question of questions) {
+    tokens += estimateStringTokens(question.question);
+    tokens += estimateStringTokens(question.instructions);
+    if (question.kind === "choice") {
+      tokens += question.choices.reduce((sum, c) => sum + estimateStringTokens(c), 0);
+    }
+  }
+
+  if (tokens > budgetTokens) {
+    throw stateTooLarge(
+      `estimated request size ${tokens} tokens exceeds the ${budgetTokens}-token budget ` +
+        `(state + questions + framing); never truncated silently — shape the state down`,
+      { estimatedTokens: tokens, budgetTokens },
+    );
+  }
+
+  return { estimatedTokens: tokens, stateBytes };
+}
+
+/** evalInputDigest (M9): stable digest of the exact evaluation input. */
+export function evalInputDigest(
+  state: unknown,
+  questions: readonly EnforcedQuestion[],
+): string {
+  const hash = createHash("sha256");
+  hash.update(canonicalJson({ state, questions }));
+  return hash.digest("hex");
+}

package/janus/janus/budget_breaker.ts

@@ -0,0 +1,105 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Daily cost breaker (§5, M10): a daily token/cost ceiling in config; on
+// exceed, /evaluate returns busy with budget_exhausted detail until the
+// window resets. Windows are UTC calendar days (the audit log uses the same
+// day key). Usage arrives from the SDK result after each evaluation; the
+// breaker is updated by the evaluate path.
+
+import { busyError } from "./errors.js";
+
+export interface UsageRecord {
+  inputTokens?: number | undefined;
+  outputTokens?: number | undefined;
+  totalTokens?: number | undefined;
+  costUsd?: number | undefined;
+}
+
+export interface BudgetStatus {
+  dayKey: string;
+  tokensUsed: number;
+  costUsdUsed: number;
+  tokenCeiling: number;
+  costCeilingUsd: number;
+  exhausted: boolean;
+}
+
+export class DailyBudget {
+  private dayKey = "";
+  private tokensUsed = 0;
+  private costUsdUsed = 0;
+
+  constructor(
+    private readonly tokenCeiling: number,
+    private readonly costCeilingUsd: number,
+    private readonly costPerMtokenUsd: number,
+    private readonly now: () => Date = () => new Date(),
+  ) {}
+
+  static dayKeyFor(date: Date): string {
+    return date.toISOString().slice(0, 10);
+  }
+
+  private rollIfNeeded(): void {
+    const key = DailyBudget.dayKeyFor(this.now());
+    if (key !== this.dayKey) {
+      this.dayKey = key;
+      this.tokensUsed = 0;
+      this.costUsdUsed = 0;
+    }
+  }
+
+  /**
+   * Record usage after an evaluation completes (success or failure after the
+   * gateway accepted the call — retries consume budget too).
+   */
+  record(usage: UsageRecord): void {
+    this.rollIfNeeded();
+    const total =
+      usage.totalTokens ??
+      (usage.inputTokens !== undefined || usage.outputTokens !== undefined
+        ? (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0)
+        : 0);
+    this.tokensUsed += total;
+    this.costUsdUsed +=
+      usage.costUsd ?? (total / 1_000_000) * this.costPerMtokenUsd;
+  }
+
+  /** Check before dispatch. Throws busy/budget_exhausted when over either ceiling. */
+  assertWithinBudget(): void {
+    this.rollIfNeeded();
+    if (this.tokenCeiling > 0 && this.tokensUsed >= this.tokenCeiling) {
+      throw busyError(
+        `daily token ceiling of ${this.tokenCeiling} reached; resets at 00:00 UTC`,
+        { budget_exhausted: { kind: "tokens", dayKey: this.dayKey, used: this.tokensUsed } },
+      );
+    }
+    if (this.costCeilingUsd > 0 && this.costUsdUsed >= this.costCeilingUsd) {
+      throw busyError(
+        `daily cost ceiling of $${this.costCeilingUsd} reached; resets at 00:00 UTC`,
+        {
+          budget_exhausted: {
+            kind: "cost",
+            dayKey: this.dayKey,
+            usedUsd: Number(this.costUsdUsed.toFixed(4)),
+          },
+        },
+      );
+    }
+  }
+
+  status(): BudgetStatus {
+    this.rollIfNeeded();
+    return {
+      dayKey: this.dayKey,
+      tokensUsed: this.tokensUsed,
+      costUsdUsed: Number(this.costUsdUsed.toFixed(4)),
+      tokenCeiling: this.tokenCeiling,
+      costCeilingUsd: this.costCeilingUsd,
+      exhausted:
+        (this.tokenCeiling > 0 && this.tokensUsed >= this.tokenCeiling) ||
+        (this.costCeilingUsd > 0 && this.costUsdUsed >= this.costCeilingUsd),
+    };
+  }
+}