ashlr-plugin 1.36.4

package/servers/_genome-sync.ts

@@ -0,0 +1,297 @@
+/**
+ * _genome-sync.ts — Plugin-side team genome sync client.
+ *
+ * Opt-in: set ASHLR_TEAM_GENOME_ID (plus existing ASHLR_PRO_TOKEN).
+ *
+ * Used by:
+ *   - hooks/session-start.ts: pull remote sections on session start
+ *   - servers/_genome-live.ts: push updated sections after ashlr__edit
+ *
+ * Design constraints:
+ *   - Never throws — all functions catch internally and log to stderr.
+ *   - Non-blocking: callers fire-and-forget (no await required).
+ *   - Tracks a local sequence number in ASHLR_GENOME_LOCAL_SEQ_PATH so
+ *     incremental pulls only fetch sections modified since last pull.
+ *
+ * Encryption (v1):
+ *   When a team key exists at ~/.ashlr/team-keys/<genomeId>.key, every
+ *   section's content is encrypted with AES-256-GCM before upload and
+ *   decrypted after pull. The server stores only ciphertext; it cannot read
+ *   section content. Vclock metadata is transmitted in plaintext so the
+ *   server can perform conflict detection without decrypting.
+ *
+ *   If no key file exists, sync falls back to plaintext (backward compat).
+ *   Existing plaintext sections are returned as-is on pull; if a section
+ *   fails to decrypt (wrong key, tamper), it is skipped with a warning.
+ */
+
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+import {
+  loadKey,
+  encryptSection,
+  decryptSection,
+  serializeBlob,
+  parseBlob,
+} from "./_genome-crypto.ts";
+
+// ---------------------------------------------------------------------------
+// Config — read at call time so tests can set env vars after module load
+// ---------------------------------------------------------------------------
+
+function cfg() {
+  return {
+    apiUrl:       process.env["ASHLR_API_URL"]               ?? "https://api.ashlr.ai",
+    genomeId:     process.env["ASHLR_TEAM_GENOME_ID"]        ?? "",
+    proToken:     process.env["ASHLR_PRO_TOKEN"]             ?? "",
+    clientId:     process.env["ASHLR_CLIENT_ID"]             ?? `client_${process.pid}`,
+    localSeqPath: process.env["ASHLR_GENOME_LOCAL_SEQ_PATH"] ?? join(homedir(), ".ashlr", "genome-seq.json"),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface RemoteSection {
+  path:              string;
+  content:           string;
+  content_encrypted: boolean;
+  vclock:            Record<string, number>;
+  conflictFlag:      boolean;
+  serverSeq:         number;
+}
+
+export interface PullResult {
+  sections:    RemoteSection[];
+  serverSeqNum: number;
+}
+
+export interface PushResult {
+  applied:   string[];
+  conflicts: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Guards
+// ---------------------------------------------------------------------------
+
+/** Returns true when team genome sync is configured. */
+export function isTeamGenomeEnabled(): boolean {
+  const { genomeId, proToken } = cfg();
+  return Boolean(genomeId && proToken);
+}
+
+// ---------------------------------------------------------------------------
+// Local seq persistence
+// ---------------------------------------------------------------------------
+
+async function readLocalSeq(): Promise<number> {
+  try {
+    const raw = await readFile(cfg().localSeqPath, "utf-8");
+    const obj = JSON.parse(raw) as { seq?: number };
+    return typeof obj.seq === "number" ? obj.seq : 0;
+  } catch {
+    return 0;
+  }
+}
+
+async function writeLocalSeq(seq: number): Promise<void> {
+  try {
+    const p = cfg().localSeqPath;
+    await mkdir(dirname(p), { recursive: true });
+    await writeFile(p, JSON.stringify({ seq }), "utf-8");
+  } catch {
+    // Non-fatal
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+
+async function apiFetch(
+  method: string,
+  path: string,
+  body?: unknown,
+): Promise<Response> {
+  const { apiUrl, proToken } = cfg();
+  const url = `${apiUrl}${path}`;
+  const init: RequestInit = {
+    method,
+    headers: {
+      Authorization: `Bearer ${proToken}`,
+      "Content-Type": "application/json",
+    },
+  };
+  if (body !== undefined) {
+    init.body = JSON.stringify(body);
+  }
+  return fetch(url, init);
+}
+
+// ---------------------------------------------------------------------------
+// Pull
+// ---------------------------------------------------------------------------
+
+/**
+ * Pull remote sections since the last known sequence number, write them to
+ * .ashlrcode/genome/sections/, update local seq.
+ *
+ * @param genomeSectionsDir  Absolute path to .ashlrcode/genome/sections/ in the repo.
+ */
+export async function pullTeamGenome(genomeSectionsDir: string): Promise<PullResult | null> {
+  if (!isTeamGenomeEnabled()) return null;
+
+  try {
+    const since = await readLocalSeq();
+    const res   = await apiFetch("GET", `/genome/${cfg().genomeId}/pull?since=${since}`);
+
+    if (!res.ok) {
+      process.stderr.write(`[ashlr-genome-sync] pull failed: ${res.status}\n`);
+      return null;
+    }
+
+    const data = await res.json() as PullResult;
+
+    if (data.sections.length > 0) {
+      await mkdir(genomeSectionsDir, { recursive: true });
+
+      // Load team key once for the whole pull (null = no key file = plaintext mode)
+      const teamKey = await loadKey(cfg().genomeId).catch(() => null);
+
+      for (const section of data.sections) {
+        const safeName = section.path.replace(/^sections\//, "");
+        // Additional client-side path safety check
+        if (safeName.includes("..") || safeName.startsWith("/") || /^[A-Za-z]:[/\\]/.test(safeName)) {
+          process.stderr.write(`[ashlr-genome-sync] skipping unsafe path: ${section.path}\n`);
+          continue;
+        }
+
+        let plaintext = section.content;
+
+        // Decrypt if the server flagged this section as encrypted and we have a key
+        if (section.content_encrypted) {
+          if (!teamKey) {
+            process.stderr.write(
+              `[ashlr-genome] WARNING: section ${section.path} is encrypted but no local key found — skipping\n`,
+            );
+            continue;
+          }
+          try {
+            const blob = parseBlob(section.content);
+            plaintext  = decryptSection(blob, teamKey);
+          } catch {
+            process.stderr.write(
+              `[ashlr-genome] WARNING: section ${section.path} failed to decrypt — wrong key or corrupt data\n`,
+            );
+            continue;
+          }
+        }
+
+        const dest = join(genomeSectionsDir, safeName);
+        await mkdir(dirname(dest), { recursive: true });
+        await writeFile(dest, plaintext, "utf-8");
+      }
+
+      await writeLocalSeq(data.serverSeqNum);
+      process.stderr.write(`[ashlr-genome-sync] pulled ${data.sections.length} section(s), seq=${data.serverSeqNum}\n`);
+    }
+
+    return data;
+  } catch (err) {
+    process.stderr.write(`[ashlr-genome-sync] pull error: ${String(err)}\n`);
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Push
+// ---------------------------------------------------------------------------
+
+/**
+ * Push a single updated section to the remote genome.
+ *
+ * @param sectionPath  Relative path within genome sections (e.g. "sections/auth.md")
+ * @param content      Full section content after the edit
+ * @param vclock       Current vector clock for this client (caller manages increment)
+ */
+export async function pushTeamGenomeSection(
+  sectionPath: string,
+  content: string,
+  vclock: Record<string, number>,
+): Promise<PushResult | null> {
+  if (!isTeamGenomeEnabled()) return null;
+
+  try {
+    const { genomeId, clientId } = cfg();
+
+    // Encrypt the section content if a team key is present
+    const teamKey = await loadKey(genomeId).catch(() => null);
+    let uploadContent = content;
+    if (teamKey) {
+      const blob    = encryptSection(content, teamKey);
+      uploadContent = serializeBlob(blob);
+    }
+
+    const res = await apiFetch("POST", `/genome/${genomeId}/push`, {
+      clientId,
+      sections: [{ path: sectionPath, content: uploadContent, vclock }],
+    });
+
+    if (!res.ok) {
+      process.stderr.write(`[ashlr-genome-sync] push failed: ${res.status}\n`);
+      return null;
+    }
+
+    const data = await res.json() as PushResult;
+
+    if (data.conflicts.length > 0) {
+      process.stderr.write(
+        `[ashlr-genome-sync] conflict on ${data.conflicts.join(", ")} — run /ashlr-genome-conflicts to resolve\n`,
+      );
+    }
+
+    return data;
+  } catch (err) {
+    process.stderr.write(`[ashlr-genome-sync] push error: ${String(err)}\n`);
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Vclock helpers (client-side)
+// ---------------------------------------------------------------------------
+
+/** Load the local vclock state from disk. Returns {} if not found. */
+export async function loadLocalVClock(genomeSectionsDir: string, sectionPath: string): Promise<Record<string, number>> {
+  const metaPath = join(genomeSectionsDir, ".vclock", sectionPath.replace(/^sections\//, "") + ".json");
+  try {
+    const raw = await readFile(metaPath, "utf-8");
+    return JSON.parse(raw) as Record<string, number>;
+  } catch {
+    return {};
+  }
+}
+
+/** Persist a vclock after a successful push. */
+export async function saveLocalVClock(
+  genomeSectionsDir: string,
+  sectionPath: string,
+  vclock: Record<string, number>,
+): Promise<void> {
+  const metaPath = join(genomeSectionsDir, ".vclock", sectionPath.replace(/^sections\//, "") + ".json");
+  try {
+    await mkdir(dirname(metaPath), { recursive: true });
+    await writeFile(metaPath, JSON.stringify(vclock), "utf-8");
+  } catch {
+    // Non-fatal
+  }
+}
+
+/** Increment this client's counter in a vclock and return the updated clock. */
+export function tickVClock(vclock: Record<string, number>, clientId = cfg().clientId): Record<string, number> {
+  return { ...vclock, [clientId]: (vclock[clientId] ?? 0) + 1 };
+}

package/servers/_history-tracker.ts

@@ -0,0 +1,279 @@
+/**
+ * _history-tracker.ts — Per-session tool result history for multi-turn staleness tracking.
+ *
+ * Records every ashlr tool result emitted this session with size + freshness metadata.
+ * Stored in ~/.ashlr/session-history/<sessionId>.jsonl (one JSONL line per result).
+ *
+ * Freshness decay (by subsequent tool-call count since emission):
+ *   turns 0–4  → 1.0 (fresh)
+ *   turns 5–14 → 0.5 (stale)
+ *   turns 15+  → 0.2 (very stale)
+ *
+ * v1.25 starting coefficients — telemetry from multi_turn_stale_estimate events will
+ * tune these in v1.26.
+ *
+ * Design:
+ *   - Best-effort only — never throws, never blocks a tool call.
+ *   - Append-only JSONL for crash-safety and cross-process reads.
+ *   - Session-scoped: each sessionId gets its own file, GC'd by session-end hook.
+ *   - Kill switch: ASHLR_SESSION_LOG=0 disables all writes.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Freshness is 1.0 for the first N turns after emission. */
+export const FRESH_TURNS = 5;
+
+/** Turns 5–14 after emission decay to this freshness. */
+export const STALE_FRESHNESS = 0.5;
+
+/** Turns 15+ after emission decay to this freshness. */
+export const VERY_STALE_FRESHNESS = 0.2;
+
+/** Results older than this many turns are considered "stale" for compaction purposes. */
+export const STALE_TURN_THRESHOLD = 5;
+
+/** Nudge threshold: total stale bytes before the adaptive nudge fires. */
+export const STALE_BYTES_NUDGE_THRESHOLD = 50 * 1024; // 50 KB
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A single history entry appended per tool call. */
+export interface HistoryEntry {
+  /** Unix ms when the result was emitted. */
+  ts: number;
+  /** Tool name (e.g. "ashlr__read", "Read"). */
+  tool: string;
+  /** Byte size of the tool result content. */
+  sizeBytes: number;
+  /** First 8 chars of SHA-256 of the result content (for dedup detection). */
+  contentSha8: string;
+  /**
+   * Global turn counter at time of emission. Starts at 0 and increments with
+   * every PostToolUse event recorded in this session (across all tools).
+   */
+  turn: number;
+  /** Session ID — redundant with the filename but useful for sanity checks. */
+  sessionId: string;
+}
+
+/** Freshness-annotated history entry (computed, not stored). */
+export interface AnnotatedEntry extends HistoryEntry {
+  /** Turns elapsed since emission (currentTurn - entry.turn). */
+  turnDelta: number;
+  /** Freshness score [0.2, 1.0]. */
+  freshness: number;
+  /** True when turnDelta >= STALE_TURN_THRESHOLD. */
+  isStale: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+
+function home(): string {
+  return process.env.ASHLR_HOME_OVERRIDE?.trim() || process.env.HOME || homedir();
+}
+
+export function historyDir(homeDir: string = home()): string {
+  return join(homeDir, ".ashlr", "session-history");
+}
+
+export function historyPath(sessionId: string, homeDir: string = home()): string {
+  return join(historyDir(homeDir), `${sessionId}.jsonl`);
+}
+
+// ---------------------------------------------------------------------------
+// Session ID resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive a session ID using the same strategy as session-start.ts:
+ *   CLAUDE_SESSION_ID → ASHLR_SESSION_ID → hash of ppid + cwd.
+ * Stable within a single Claude Code session because ppid + cwd are constant.
+ */
+export function resolveSessionId(): string {
+  const explicit =
+    process.env.CLAUDE_SESSION_ID?.trim() ||
+    process.env.ASHLR_SESSION_ID?.trim();
+  if (explicit) return explicit;
+  const seed = `${process.ppid ?? process.pid}:${process.cwd()}`;
+  let h = 0;
+  for (let i = 0; i < seed.length; i++) h = ((h << 5) - h + seed.charCodeAt(i)) | 0;
+  return `h${(h >>> 0).toString(16)}`;
+}
+
+// ---------------------------------------------------------------------------
+// SHA-8 helper
+// ---------------------------------------------------------------------------
+
+/** Compute first 8 hex chars of a simple djb2 hash (no native crypto needed). */
+export function sha8(content: string): string {
+  let h = 5381;
+  for (let i = 0; i < content.length; i++) {
+    h = ((h << 5) + h + content.charCodeAt(i)) | 0;
+  }
+  return (h >>> 0).toString(16).padStart(8, "0").slice(0, 8);
+}
+
+// ---------------------------------------------------------------------------
+// Current turn counter
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the current session turn count from the history file.
+ * Turn = number of entries already written (0-indexed).
+ */
+export function readCurrentTurn(sessionId: string, homeDir: string = home()): number {
+  try {
+    const p = historyPath(sessionId, homeDir);
+    if (!existsSync(p)) return 0;
+    const raw = readFileSync(p, "utf-8");
+    const lines = raw.split("\n").filter((l) => l.trim().length > 0);
+    return lines.length;
+  } catch {
+    return 0;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Record a result
+// ---------------------------------------------------------------------------
+
+/**
+ * Append one history entry for a completed tool call.
+ * Best-effort — never throws.
+ *
+ * @param tool       Tool name from PostToolUse payload.
+ * @param content    String representation of the result (for size + sha8).
+ * @param sessionId  Override for testing.
+ * @param homeDir    Override for testing.
+ * @param now        Override for testing.
+ */
+export function recordResult(
+  tool: string,
+  content: string,
+  sessionId: string = resolveSessionId(),
+  homeDir: string = home(),
+  now: number = Date.now(),
+): void {
+  if (process.env.ASHLR_SESSION_LOG === "0") return;
+
+  try {
+    const dir = historyDir(homeDir);
+    mkdirSync(dir, { recursive: true });
+
+    const turn = readCurrentTurn(sessionId, homeDir);
+    const entry: HistoryEntry = {
+      ts: now,
+      tool,
+      sizeBytes: Buffer.byteLength(content, "utf-8"),
+      contentSha8: sha8(content),
+      turn,
+      sessionId,
+    };
+
+    appendFileSync(historyPath(sessionId, homeDir), JSON.stringify(entry) + "\n", "utf-8");
+  } catch {
+    // Best-effort — never block the tool call.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Read and annotate history
+// ---------------------------------------------------------------------------
+
+/**
+ * Read all history entries for a session.
+ * Returns [] on any error.
+ */
+export function readHistory(
+  sessionId: string = resolveSessionId(),
+  homeDir: string = home(),
+): HistoryEntry[] {
+  try {
+    const p = historyPath(sessionId, homeDir);
+    if (!existsSync(p)) return [];
+    const raw = readFileSync(p, "utf-8");
+    return raw
+      .split("\n")
+      .filter((l) => l.trim().length > 0)
+      .map((l) => {
+        try { return JSON.parse(l) as HistoryEntry; } catch { return null; }
+      })
+      .filter((e): e is HistoryEntry => e !== null);
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Freshness computation
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute freshness score given the number of turns since emission.
+ *
+ *   0–4 turns  → 1.0
+ *   5–14 turns → 0.5
+ *   15+ turns  → 0.2
+ */
+export function freshnessScore(turnDelta: number): number {
+  if (turnDelta < FRESH_TURNS) return 1.0;
+  if (turnDelta < 15) return STALE_FRESHNESS;
+  return VERY_STALE_FRESHNESS;
+}
+
+/**
+ * Annotate all history entries with freshness metadata relative to currentTurn.
+ */
+export function annotateHistory(
+  entries: HistoryEntry[],
+  currentTurn: number,
+): AnnotatedEntry[] {
+  return entries.map((e) => {
+    const turnDelta = Math.max(0, currentTurn - e.turn);
+    const freshness = freshnessScore(turnDelta);
+    return {
+      ...e,
+      turnDelta,
+      freshness,
+      isStale: turnDelta >= STALE_TURN_THRESHOLD,
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Stale byte total
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute total byte size of stale results in the current session.
+ * Used by the adaptive nudge and /ashlr-compact.
+ */
+export function staleByteTotal(
+  sessionId: string = resolveSessionId(),
+  homeDir: string = home(),
+): { staleBytes: number; staleResults: number; sessionTurnCount: number } {
+  try {
+    const entries = readHistory(sessionId, homeDir);
+    const currentTurn = entries.length;
+    const annotated = annotateHistory(entries, currentTurn);
+    const stale = annotated.filter((e) => e.isStale);
+    return {
+      staleBytes: stale.reduce((acc, e) => acc + e.sizeBytes, 0),
+      staleResults: stale.length,
+      sessionTurnCount: currentTurn,
+    };
+  } catch {
+    return { staleBytes: 0, staleResults: 0, sessionTurnCount: 0 };
+  }
+}