@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/claw-compactor/proxy/session-affinity.mjs

@@ -0,0 +1,177 @@
+/**
+ * Session Affinity — sticky routing for conversation sessions.
+ *
+ * Maps session keys to workers so the same conversation always
+ * routes to the same CLI instance (preserving rate-limit budgets
+ * and enabling future persistent sessions).
+ *
+ * Session key priority:
+ *   1. x-session-id header (explicit, most precise)
+ *   2. source + systemPrompt hash (same conversation = same prompt prefix)
+ *   3. source alone (coarse fallback)
+ *
+ * Entries expire after TTL_MS of inactivity.
+ */
+
+const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 min
+const SWEEP_INTERVAL_MS = 60 * 1000;   // 1 min
+
+/**
+ * @param {object} opts
+ * @param {number} [opts.ttlMs]           Inactivity TTL (default 30 min)
+ * @param {number} [opts.sweepIntervalMs] Cleanup interval (default 60s)
+ * @returns {SessionAffinity}
+ */
+export function createSessionAffinity(opts = {}) {
+  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const sweepMs = opts.sweepIntervalMs ?? SWEEP_INTERVAL_MS;
+
+  // sessionKey -> { workerName, lastUsedAt, createdAt, requestCount }
+  const _map = new Map();
+
+  let _hits = 0;
+  let _misses = 0;
+  let _reassigns = 0;
+
+  // Periodic sweep of stale entries
+  const _sweepTimer = setInterval(() => {
+    const now = Date.now();
+    for (const [key, entry] of _map) {
+      if (now - entry.lastUsedAt > ttlMs) {
+        _map.delete(key);
+      }
+    }
+  }, sweepMs);
+  _sweepTimer.unref?.();
+
+  /**
+   * Derive a session key from request context.
+   *
+   * @param {object} ctx
+   * @param {string} ctx.source        - Client source identifier
+   * @param {string} [ctx.sessionId]   - Explicit session ID (x-session-id header)
+   * @param {string} [ctx.systemPrompt] - System prompt (for fingerprinting)
+   * @returns {string} sessionKey
+   */
+  function deriveKey(ctx) {
+    // 1. Explicit session ID is most precise
+    if (ctx.sessionId) {
+      return `sid:${ctx.sessionId}`;
+    }
+
+    // 2. Source + system prompt hash — same conversation usually keeps
+    //    the same system prompt across turns
+    if (ctx.systemPrompt) {
+      const hash = simpleHash(ctx.systemPrompt.slice(0, 200));
+      return `sp:${ctx.source}:${hash}`;
+    }
+
+    // 3. Source alone
+    return `src:${ctx.source}`;
+  }
+
+  /**
+   * Look up the affinity worker for a session.
+   *
+   * @param {string} sessionKey
+   * @param {function} isWorkerHealthy - (workerName) => boolean
+   * @returns {{ workerName: string, hit: boolean } | null}
+   *   - hit=true: existing affinity, worker is healthy
+   *   - hit=false: existing affinity but worker unhealthy (caller should reassign)
+   *   - null: no affinity exists (caller should assign via round-robin)
+   */
+  function lookup(sessionKey, isWorkerHealthy) {
+    const entry = _map.get(sessionKey);
+    if (!entry) {
+      _misses++;
+      return null;
+    }
+
+    // Touch the entry
+    entry.lastUsedAt = Date.now();
+    entry.requestCount++;
+
+    if (isWorkerHealthy(entry.workerName)) {
+      _hits++;
+      return { workerName: entry.workerName, hit: true };
+    }
+
+    // Worker is unhealthy — caller will reassign
+    _reassigns++;
+    return { workerName: entry.workerName, hit: false };
+  }
+
+  /**
+   * Assign (or reassign) a worker to a session.
+   *
+   * @param {string} sessionKey
+   * @param {string} workerName
+   */
+  function assign(sessionKey, workerName) {
+    const existing = _map.get(sessionKey);
+    if (existing) {
+      // Reassign — preserve creation time and count
+      existing.workerName = workerName;
+      existing.lastUsedAt = Date.now();
+      return;
+    }
+    _map.set(sessionKey, {
+      workerName,
+      createdAt: Date.now(),
+      lastUsedAt: Date.now(),
+      requestCount: 1,
+    });
+  }
+
+  /**
+   * Remove a specific session's affinity.
+   */
+  function remove(sessionKey) {
+    _map.delete(sessionKey);
+  }
+
+  /**
+   * Get stats for monitoring.
+   */
+  function getStats() {
+    const total = _hits + _misses + _reassigns;
+    return {
+      activeSessions: _map.size,
+      hits: _hits,
+      misses: _misses,
+      reassigns: _reassigns,
+      hitRate: total > 0 ? (_hits / total * 100).toFixed(1) + "%" : "0%",
+      totalLookups: total,
+    };
+  }
+
+  /**
+   * Shutdown — clear timer.
+   */
+  function shutdown() {
+    clearInterval(_sweepTimer);
+    _map.clear();
+  }
+
+  return {
+    deriveKey,
+    lookup,
+    assign,
+    remove,
+    getStats,
+    shutdown,
+  };
+}
+
+/**
+ * Fast, non-crypto hash for session fingerprinting.
+ * FNV-1a 32-bit.
+ */
+function simpleHash(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = (h * 0x01000193) >>> 0;
+  }
+  return h.toString(36);
+}

package/skills/claw-compactor/proxy/start.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# start.sh — Launch claude-code-proxy
+# Usage: ./start.sh          (foreground)
+#        ./start.sh --bg     (background, logs to /tmp/claude-proxy.log)
+
+DIR="$(cd "$(dirname "$0")" && pwd)"
+export PATH="/opt/homebrew/bin:$PATH"
+
+# Kill existing proxy if running
+EXISTING_PID=$(pgrep -f "node.*claude-code-proxy/server.mjs")
+if [ -n "$EXISTING_PID" ]; then
+  echo "Stopping existing proxy (PID $EXISTING_PID)..."
+  kill "$EXISTING_PID" 2>/dev/null
+  sleep 2
+fi
+
+if [ "$1" = "--bg" ]; then
+  nohup /opt/homebrew/bin/node "$DIR/server.mjs" >> /tmp/claude-proxy.log 2>&1 &
+  echo "Proxy started in background (PID $!)"
+  echo "Logs: /tmp/claude-proxy.log"
+else
+  exec /opt/homebrew/bin/node "$DIR/server.mjs"
+fi

package/skills/claw-compactor/proxy/test/event-log.test.mjs

@@ -0,0 +1,237 @@
+/**
+ * Tests for event-log.mjs
+ *
+ * Verifies: push, getRecent, getCounts, clear,
+ *           Redis LIST persistence, circular buffer behavior.
+ */
+
+import { describe, it, after } from "node:test";
+import assert from "node:assert/strict";
+import { createEventLog } from "../event-log.mjs";
+import { createTestRedis, cleanupTestRedis, sleep } from "./helpers.mjs";
+// Note: cleanupTestRedis used both in after() and per-test for isolation
+
+describe("event-log", () => {
+  let redis = null;
+
+  after(async () => {
+    if (redis) await cleanupTestRedis(redis);
+  });
+
+  describe("in-memory (no Redis)", () => {
+    it("should push and retrieve events", () => {
+      const log = createEventLog({ maxEvents: 100 });
+
+      const event = log.push("request", { reqId: "r1", model: "sonnet" });
+      assert.ok(event, "Should return event");
+      assert.equal(event.type, "request");
+      assert.equal(event.reqId, "r1");
+      assert.ok(event.id > 0, "Should have positive ID");
+      assert.ok(event.ts > 0, "Should have timestamp");
+      assert.ok(event.isoTs, "Should have ISO timestamp");
+    });
+
+    it("should auto-increment event IDs", () => {
+      const log = createEventLog({ maxEvents: 100 });
+
+      const e1 = log.push("request", {});
+      const e2 = log.push("error", {});
+      const e3 = log.push("retry", {});
+
+      assert.equal(e2.id, e1.id + 1);
+      assert.equal(e3.id, e2.id + 1);
+    });
+
+    it("should getRecent with default limit", () => {
+      const log = createEventLog({ maxEvents: 100 });
+
+      for (let i = 0; i < 10; i++) {
+        log.push("request", { i });
+      }
+
+      const recent = log.getRecent();
+      assert.equal(recent.length, 10);
+    });
+
+    it("should getRecent with limit", () => {
+      const log = createEventLog({ maxEvents: 100 });
+
+      for (let i = 0; i < 10; i++) {
+        log.push("request", { i });
+      }
+
+      const recent = log.getRecent({ limit: 5 });
+      assert.equal(recent.length, 5);
+      // Should be the last 5
+      assert.equal(recent[4].i, 9);
+    });
+
+    it("should filter by sinceId", () => {
+      const log = createEventLog({ maxEvents: 100 });
+
+      const e1 = log.push("request", {});
+      const e2 = log.push("error", {});
+      const e3 = log.push("retry", {});
+
+      const after = log.getRecent({ sinceId: e1.id });
+      assert.equal(after.length, 2);
+      assert.equal(after[0].id, e2.id);
+      assert.equal(after[1].id, e3.id);
+    });
+
+    it("should filter by type", () => {
+      const log = createEventLog({ maxEvents: 100 });
+
+      log.push("request", { model: "sonnet" });
+      log.push("error", { msg: "fail" });
+      log.push("request", { model: "opus" });
+      log.push("retry", { attempt: 1 });
+
+      const requests = log.getRecent({ type: "request" });
+      assert.equal(requests.length, 2);
+      assert.ok(requests.every((e) => e.type === "request"));
+    });
+
+    it("should track counts by type", () => {
+      const log = createEventLog({ maxEvents: 100 });
+
+      log.push("request", {});
+      log.push("request", {});
+      log.push("error", {});
+      log.push("retry", {});
+      log.push("retry", {});
+      log.push("retry", {});
+
+      const counts = log.getCounts();
+      assert.equal(counts.request, 2);
+      assert.equal(counts.error, 1);
+      assert.equal(counts.retry, 3);
+    });
+
+    it("should enforce maxEvents circular buffer", () => {
+      const log = createEventLog({ maxEvents: 5 });
+
+      for (let i = 0; i < 10; i++) {
+        log.push("request", { i });
+      }
+
+      const recent = log.getRecent({ limit: 100 });
+      assert.equal(recent.length, 5, "Should cap at maxEvents");
+      // Should have the last 5
+      assert.equal(recent[0].i, 5);
+      assert.equal(recent[4].i, 9);
+    });
+
+    it("should return frozen objects", () => {
+      const log = createEventLog({ maxEvents: 100 });
+      const event = log.push("test", { data: "hello" });
+      assert.ok(Object.isFrozen(event));
+      assert.ok(Object.isFrozen(log.getCounts()));
+    });
+
+    it("should clear events but preserve counts as reset", () => {
+      const log = createEventLog({ maxEvents: 100 });
+
+      log.push("request", {});
+      log.push("error", {});
+
+      log.clear();
+
+      const recent = log.getRecent();
+      assert.equal(recent.length, 0, "Events should be cleared");
+
+      const counts = log.getCounts();
+      assert.deepEqual(counts, {}, "Counts should be cleared");
+    });
+  });
+
+  describe("with Redis", () => {
+    it("should persist events to Redis LIST", async () => {
+      redis = await createTestRedis();
+      const log = createEventLog({ maxEvents: 100, redis });
+      await log.ready;
+
+      log.push("request", { reqId: "r-redis-1" });
+      log.push("error", { msg: "test error" });
+
+      await sleep(200);
+
+      // Check Redis LIST length
+      const len = await redis.client.llen("events");
+      assert.ok(len >= 2, `Redis should have at least 2 events, got ${len}`);
+    });
+
+    it("should persist counts to Redis HASH", async () => {
+      // Use fresh Redis to avoid accumulated data from previous test
+      const freshRedis = await createTestRedis();
+      const log = createEventLog({ maxEvents: 100, redis: freshRedis });
+      await log.ready;
+
+      log.push("request", {});
+      log.push("request", {});
+      log.push("error", {});
+
+      await sleep(200);
+
+      const count = await freshRedis.client.hget("events:counts", "request");
+      assert.ok(parseInt(count, 10) >= 2, `Request count should be >= 2, got ${count}`);
+      await cleanupTestRedis(freshRedis);
+    });
+
+    it("should persist and load nextId", async () => {
+      // Use fresh Redis for isolation
+      const freshRedis = await createTestRedis();
+      const log1 = createEventLog({ maxEvents: 100, redis: freshRedis });
+      await log1.ready;
+
+      const e1 = log1.push("test", {});
+      const e2 = log1.push("test", {});
+
+      await sleep(200);
+
+      // Create a new instance — it should load nextId from Redis
+      const log2 = createEventLog({ maxEvents: 100, redis: freshRedis });
+      await log2.ready;
+
+      const e3 = log2.push("test", {});
+      assert.ok(e3.id > e2.id, `New ID ${e3.id} should be > previous ${e2.id}`);
+      await cleanupTestRedis(freshRedis);
+    });
+
+    it("should load events from Redis on startup", async () => {
+      // Use fresh Redis for isolation
+      const freshRedis = await createTestRedis();
+      const log1 = createEventLog({ maxEvents: 100, redis: freshRedis });
+      await log1.ready;
+
+      log1.push("startup", { version: "test" });
+      log1.push("request", { reqId: "r-load-1" });
+
+      await sleep(200);
+
+      // New instance should load from Redis
+      const log2 = createEventLog({ maxEvents: 100, redis: freshRedis });
+      await log2.ready;
+
+      const recent = log2.getRecent({ type: "startup" });
+      assert.ok(recent.length >= 1, "Should have loaded startup events from Redis");
+      await cleanupTestRedis(freshRedis);
+    });
+
+    it("should cap Redis LIST at maxEvents", async () => {
+      const log = createEventLog({ maxEvents: 10, redis });
+      await log.ready;
+
+      for (let i = 0; i < 15; i++) {
+        log.push("test", { i });
+      }
+
+      await sleep(300);
+
+      const len = await redis.client.llen("events");
+      // May have extra from other tests using same redis, but shouldn't grow unbounded
+      // The ltrim keeps it at maxEvents
+      assert.ok(len <= 20, `Redis LIST should be capped, got ${len}`);
+    });
+  });
+});

package/skills/claw-compactor/proxy/test/helpers.mjs

@@ -0,0 +1,103 @@
+/**
+ * Test Helpers — Shared Redis setup/teardown for all tests.
+ *
+ * Each call to createTestRedis() generates a unique prefix so
+ * concurrent test files don't interfere with each other.
+ */
+
+import Redis from "ioredis";
+
+let counter = 0;
+
+/**
+ * Create a Redis client with a unique test-specific key prefix.
+ * Each invocation gets its own prefix to avoid cross-test interference.
+ * @returns {{ client, isReady, quit, ping, prefix }}
+ */
+export async function createTestRedis() {
+  const prefix = `ccp:test:${Date.now()}:${++counter}:`;
+
+  const client = new Redis("redis://127.0.0.1:6379", {
+    keyPrefix: prefix,
+    lazyConnect: true,
+    maxRetriesPerRequest: 1,
+    connectTimeout: 3000,
+    enableOfflineQueue: false,
+  });
+
+  let ready = false;
+
+  client.on("ready", () => { ready = true; });
+  client.on("close", () => { ready = false; });
+
+  await client.connect();
+
+  return Object.freeze({
+    client,
+    isReady: () => ready,
+    quit: () => client.quit(),
+    ping: () => client.ping(),
+    prefix,
+  });
+}
+
+/**
+ * Clean up all test keys from Redis for a specific client.
+ * Uses SCAN to find and delete keys with that client's unique prefix.
+ */
+export async function cleanupTestRedis(redis) {
+  if (!redis?.isReady()) return;
+
+  const prefix = redis.prefix;
+
+  try {
+    // Use raw client (without prefix) to scan for prefixed keys
+    const rawClient = new Redis("redis://127.0.0.1:6379", {
+      lazyConnect: true,
+      maxRetriesPerRequest: 1,
+    });
+    await rawClient.connect();
+
+    let cursor = "0";
+    do {
+      const [nextCursor, keys] = await rawClient.scan(
+        cursor,
+        "MATCH",
+        `${prefix}*`,
+        "COUNT",
+        100,
+      );
+      cursor = nextCursor;
+      if (keys.length > 0) {
+        await rawClient.del(...keys);
+      }
+    } while (cursor !== "0");
+
+    await rawClient.quit();
+  } catch (err) {
+    console.error(`[TestHelper] Cleanup error: ${err.message}`);
+  }
+
+  await redis.quit();
+}
+
+/**
+ * Create a mock Redis that always reports not ready.
+ * Used for testing graceful fallback behavior.
+ */
+export function createMockDisabledRedis() {
+  return Object.freeze({
+    client: null,
+    isReady: () => false,
+    quit: async () => {},
+    ping: async () => { throw new Error("Redis disabled"); },
+    prefix: "ccp:mock:",
+  });
+}
+
+/**
+ * Sleep helper.
+ */
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}