@cgh567/agent 2.4.2 → 2.4.4

package/lib/compression/__tests__/pipeline.test.js

@@ -0,0 +1,280 @@
+/**
+ * lib/compression/__tests__/pipeline.test.js
+ *
+ * Unit tests for CompressionPipeline and ContentRouter.
+ * Tests: message routing, system message skip, tool_result compression,
+ *        headroom_retrieve protection, content type detection.
+ *
+ * No mocks — tests real behavior.
+ */
+'use strict';
+
+const { describe, it, expect, beforeEach, afterEach } = require('vitest');
+const { CompressionPipeline } = require('../dist/pipeline.js');
+const { ContentRouter, detectContentType } = require('../dist/content-router.js');
+const { CcrStore } = require('../dist/ccr-store.js');
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function makeUniformJson(n) {
+  return JSON.stringify(
+    Array.from({ length: n }, (_, i) => ({
+      id: `lead-${String(i).padStart(4, '0')}`,
+      type: 'signal',
+      status: i % 2 === 0 ? 'active' : 'inactive',
+      score: 70 + (i % 30),
+      source: 'salesforce',
+      ts: `2026-06-${String((i % 28) + 1).padStart(2, '0')}T00:00:00Z`,
+    }))
+  );
+}
+
+function makeMessages(toolResultContent) {
+  return [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'What signals are there?' },
+    {
+      role: 'assistant',
+      content: [{ type: 'tool_use', id: 'tu_001', name: 'get_signals', input: {} }],
+    },
+    {
+      role: 'user',
+      content: [
+        {
+          type: 'tool_result',
+          tool_use_id: 'tu_001',
+          content: toolResultContent,
+        },
+      ],
+    },
+  ];
+}
+
+// ── detectContentType ─────────────────────────────────────────────────────────
+
+describe('detectContentType', () => {
+  it('detects JSON_ARRAY for array input', () => {
+    expect(detectContentType('[{"id":1},{"id":2}]')).toBe('JSON_ARRAY');
+  });
+
+  it('detects JSON_OBJECT for object input', () => {
+    expect(detectContentType('{"key":"value"}')).toBe('JSON_OBJECT');
+  });
+
+  it('detects SOURCE_CODE for backtick code block', () => {
+    expect(detectContentType('```js\nconsole.log("hi")\n```')).toBe('SOURCE_CODE');
+  });
+
+  it('detects SOURCE_CODE for function keyword', () => {
+    expect(detectContentType('Some text\nfunction foo() { return 1; }')).toBe('SOURCE_CODE');
+  });
+
+  it('detects PLAIN_TEXT for regular prose', () => {
+    expect(detectContentType('The agent should focus on high-priority leads.')).toBe('PLAIN_TEXT');
+  });
+
+  it('returns PLAIN_TEXT for malformed JSON that starts with [', () => {
+    expect(detectContentType('[not valid json')).toBe('PLAIN_TEXT');
+  });
+});
+
+// ── ContentRouter ─────────────────────────────────────────────────────────────
+
+describe('ContentRouter — protection gates', () => {
+  let router;
+  let store;
+  beforeEach(() => {
+    router = new ContentRouter();
+    store = new CcrStore(60);
+  });
+  afterEach(() => { store.destroy(); });
+
+  it('returns passthrough for content shorter than 500 chars', () => {
+    const short = makeUniformJson(3); // tiny array
+    expect(short.length).toBeLessThan(500);
+    const result = router.route(short, 'some_tool', store);
+    expect(result.compressed).toBe(false);
+    expect(result.tokensSaved).toBe(0);
+  });
+
+  it('never compresses headroom_retrieve tool results (infinite loop prevention)', () => {
+    const large = makeUniformJson(30);
+    expect(large.length).toBeGreaterThan(500);
+    const result = router.route(large, 'headroom_retrieve', store);
+    expect(result.compressed).toBe(false);
+    expect(result.strategy).toBe('passthrough');
+  });
+
+  it('does not compress small error outputs (<=8000 chars + error keyword)', () => {
+    const errorOut = JSON.stringify({ error: 'timeout', traceback: 'at line 42' }) + ' '.repeat(100);
+    const result = router.route(errorOut, 'bash', store);
+    // Passthrough because: contains "error" AND length <= 8000
+    expect(result.compressed).toBe(false);
+  });
+
+  it('compresses large error-containing payloads (>8000 chars)', () => {
+    // > 8000 chars with error key — protection does NOT apply
+    const largeWithError = JSON.stringify(
+      Array.from({ length: 30 }, (_, i) => ({
+        id: `e-${i}`,
+        type: 'signal',
+        status: 'active',
+        score: 80,
+        source: 'crm',
+        ts: `2026-06-${String(i % 28 + 1).padStart(2, '0')}T00:00:00Z`,
+        extra: 'padding'.repeat(20),
+      }))
+    );
+    expect(largeWithError.length).toBeGreaterThan(8000);
+    const result = router.route(largeWithError, 'get_signals', store);
+    // Should be compressed (not a small error output)
+    expect(result.compressed).toBe(true);
+  });
+});
+
+describe('ContentRouter — compression', () => {
+  let router;
+  let store;
+  beforeEach(() => {
+    router = new ContentRouter();
+    store = new CcrStore(60);
+  });
+  afterEach(() => { store.destroy(); });
+
+  it('compresses a large JSON_ARRAY to lossless-csv', () => {
+    const content = makeUniformJson(30);
+    const result = router.route(content, 'get_signals', store);
+    expect(result.compressed).toBe(true);
+    expect(result.contentType).toBe('JSON_ARRAY');
+    expect(result.tokensSaved).toBeGreaterThan(0);
+  });
+
+  it('returns passthrough for PLAIN_TEXT', () => {
+    const text = 'The agent should focus on high-priority leads. '.repeat(30);
+    expect(text.length).toBeGreaterThan(500);
+    const result = router.route(text, 'recall', store);
+    expect(result.compressed).toBe(false);
+  });
+
+  it('returns passthrough for JSON_OBJECT', () => {
+    const obj = JSON.stringify({ items: [1, 2, 3], count: 3, total: 6 }) + ' '.repeat(600);
+    const result = router.route(obj, 'get_stats', store);
+    expect(result.compressed).toBe(false);
+  });
+});
+
+// ── CompressionPipeline ───────────────────────────────────────────────────────
+
+describe('CompressionPipeline — message routing', () => {
+  let pipeline;
+  let store;
+  beforeEach(() => {
+    pipeline = new CompressionPipeline();
+    store = new CcrStore(60);
+  });
+  afterEach(() => { store.destroy(); });
+
+  it('compresses tool_result blocks in user messages', () => {
+    const messages = makeMessages(makeUniformJson(30));
+    const result = pipeline.compress(messages, store);
+    expect(result.tokensSaved).toBeGreaterThan(0);
+    expect(result.transformsApplied.length).toBeGreaterThan(0);
+  });
+
+  it('does NOT mutate original messages array', () => {
+    const messages = makeMessages(makeUniformJson(30));
+    const originalJson = JSON.stringify(messages);
+    pipeline.compress(messages, store);
+    expect(JSON.stringify(messages)).toBe(originalJson);
+  });
+
+  it('skips system messages (preserves prompt cache stability)', () => {
+    const systemContent = 'You are a helpful assistant.';
+    const messages = [
+      { role: 'system', content: systemContent },
+      {
+        role: 'user',
+        content: [
+          { type: 'tool_result', tool_use_id: 'tu_1', content: makeUniformJson(30) },
+        ],
+      },
+    ];
+    const result = pipeline.compress(messages, store);
+    // System message content must be unchanged
+    expect(result.messages[0].content).toBe(systemContent);
+  });
+
+  it('skips non-tool_result blocks in user messages', () => {
+    const messages = [
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'What are the signals?' },
+          { type: 'tool_result', tool_use_id: 'tu_1', content: makeUniformJson(30) },
+        ],
+      },
+    ];
+    const result = pipeline.compress(messages, store);
+    // Text block must be unchanged
+    expect(result.messages[0].content[0].type).toBe('text');
+    expect(result.messages[0].content[0].text).toBe('What are the signals?');
+    // tool_result block should be compressed
+    expect(result.tokensSaved).toBeGreaterThan(0);
+  });
+
+  it('returns compressionRatio < 1 when compression succeeds', () => {
+    const messages = makeMessages(makeUniformJson(30));
+    const result = pipeline.compress(messages, store);
+    expect(result.compressionRatio).toBeGreaterThan(0);
+    expect(result.compressionRatio).toBeLessThan(1);
+  });
+
+  it('returns compressionRatio = 1 for uncompressible input', () => {
+    // String content that's too short to compress
+    const messages = [
+      { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'tu_1', content: 'hi' }] },
+    ];
+    const result = pipeline.compress(messages, store);
+    expect(result.tokensSaved).toBe(0);
+    expect(result.compressionRatio).toBe(1);
+  });
+
+  it('collects ccrHashes when lossy-sample is applied', () => {
+    // Sparse array to trigger lossy-sample
+    const pad = 'x'.repeat(200);
+    const sparse = JSON.stringify(
+      Array.from({ length: 40 }, (_, i) => {
+        const o = { id: `item-${String(i).padStart(5, '0')}` };
+        if (i % 2 === 0) o.payload = `data_${i}_${pad}`;
+        if (i % 3 === 0) o.stage = 'active';
+        if (i % 4 === 0) o.value = i * 100;
+        if (i % 5 === 0) o.ts = `2026-06-${String((i % 28) + 1).padStart(2, '0')}`;
+        if (i % 6 === 0) o.owner = `rep-${i % 8}`;
+        if (i % 7 === 0) o.src = 'crm';
+        return o;
+      })
+    );
+    const messages = makeMessages(sparse);
+    const result = pipeline.compress(messages, store);
+    if (result.transformsApplied.includes('lossy-sample')) {
+      expect(result.ccrHashes.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('handles empty messages array', () => {
+    const result = pipeline.compress([], store);
+    expect(result.messages).toEqual([]);
+    expect(result.tokensSaved).toBe(0);
+    expect(result.compressionRatio).toBe(1);
+  });
+
+  it('handles messages with string content (not array)', () => {
+    const messages = [
+      { role: 'user', content: 'simple string content' },
+      { role: 'assistant', content: 'simple assistant response' },
+    ];
+    const result = pipeline.compress(messages, store);
+    expect(result.messages[0].content).toBe('simple string content');
+    expect(result.tokensSaved).toBe(0);
+  });
+});

package/lib/compression/__tests__/smart-crusher.test.js

@@ -0,0 +1,242 @@
+/**
+ * lib/compression/__tests__/smart-crusher.test.js
+ *
+ * Unit tests for SmartCrusher.
+ * Tests: lossless-csv path, lossy-sample path, passthrough gates,
+ *        CCR storage, savings ratio threshold.
+ *
+ * No mocks — tests the real SmartCrusher implementation.
+ */
+'use strict';
+
+const { describe, it, expect, beforeEach } = require('vitest');
+const { SmartCrusher, DEFAULT_CRUSHER_CONFIG } = require('../dist/smart-crusher.js');
+const { CcrStore } = require('../dist/ccr-store.js');
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function makeUniform(n, extraFields = {}) {
+  return Array.from({ length: n }, (_, i) => ({
+    id: `lead-${String(i).padStart(4, '0')}`,
+    type: 'signal',
+    status: i % 3 === 0 ? 'active' : 'inactive',
+    score: 70 + (i % 30),
+    source: 'salesforce',
+    ...extraFields,
+  }));
+}
+
+function makeSparse(n) {
+  // Each item has only 'id' as a universal field — no lossless-csv possible
+  return Array.from({ length: n }, (_, i) => {
+    const base = { id: `rec-${i}` };
+    if (i % 2 === 0) base.a = `a_${i}`;
+    if (i % 3 === 0) base.b = `b_${i}`;
+    if (i % 5 === 0) base.c = `c_${i}`;
+    if (i % 7 === 0) base.d = `d_${i}`;
+    // Pad to exceed 500 char min
+    base.pad = 'x'.repeat(30);
+    return base;
+  });
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe('SmartCrusher — passthrough gates', () => {
+  let crusher;
+  beforeEach(() => { crusher = new SmartCrusher(); });
+
+  it('returns passthrough for input shorter than minCharsToCompress (200)', () => {
+    const tiny = JSON.stringify([{ id: 1 }, { id: 2 }]);
+    expect(tiny.length).toBeLessThan(DEFAULT_CRUSHER_CONFIG.minCharsToCompress);
+    const result = crusher.compress(tiny, null);
+    expect(result.compressed).toBe(false);
+    expect(result.strategy).toBe('passthrough');
+  });
+
+  it('returns passthrough for non-JSON input', () => {
+    const text = 'This is plain text, not JSON. '.repeat(20);
+    const result = crusher.compress(text, null);
+    expect(result.compressed).toBe(false);
+    expect(result.strategy).toBe('passthrough');
+  });
+
+  it('returns passthrough for JSON object (not array)', () => {
+    const obj = JSON.stringify({ key: 'value', items: [1, 2, 3] });
+    const result = crusher.compress(obj, null);
+    expect(result.compressed).toBe(false);
+    expect(result.strategy).toBe('passthrough');
+  });
+
+  it('returns passthrough for arrays smaller than minItemsToAnalyze (5)', () => {
+    const small = JSON.stringify(makeUniform(4));
+    const result = crusher.compress(small, null);
+    expect(result.compressed).toBe(false);
+    expect(result.strategy).toBe('passthrough');
+  });
+
+  it('returns passthrough when lossless savings < losslessMinSavingsRatio (15%)', () => {
+    // A 5-item array — lossless might not save enough; if it doesn't, should passthrough
+    const arr = JSON.stringify(makeUniform(5));
+    const result = crusher.compress(arr, null);
+    // Either passthrough or lossless-csv — never lossy-sample for 5 items
+    if (!result.compressed) {
+      expect(result.strategy).toBe('passthrough');
+    } else {
+      expect(result.strategy).toBe('lossless-csv');
+    }
+  });
+});
+
+describe('SmartCrusher — lossless-csv path', () => {
+  let crusher;
+  beforeEach(() => { crusher = new SmartCrusher(); });
+
+  it('compresses a 30-item uniform array to lossless-csv', () => {
+    const input = JSON.stringify(makeUniform(30));
+    const result = crusher.compress(input, null);
+    expect(result.compressed).toBe(true);
+    expect(result.strategy).toBe('lossless-csv');
+    expect(result.rowsDropped).toBe(0);
+    expect(result.output).toContain('[csv:');
+  });
+
+  it('lossless-csv output contains header row', () => {
+    const input = JSON.stringify(makeUniform(20));
+    const result = crusher.compress(input, null);
+    if (result.strategy !== 'lossless-csv') return; // skip if not triggered
+    // Header should contain field names separated by tabs
+    const lines = result.output.split('\n');
+    const headerLine = lines.find((l) => l.includes('\t'));
+    expect(headerLine).toBeTruthy();
+  });
+
+  it('savings ratio >= 15% for 30-item uniform array', () => {
+    const input = JSON.stringify(makeUniform(30));
+    const result = crusher.compress(input, null);
+    if (result.strategy !== 'lossless-csv') return;
+    const savings = 1 - result.output.length / input.length;
+    expect(savings).toBeGreaterThanOrEqual(DEFAULT_CRUSHER_CONFIG.losslessMinSavingsRatio);
+  });
+
+  it('rejects arrays with fewer than 3 core fields', () => {
+    // Array where only 1 field appears in >=80% of items
+    const arr = Array.from({ length: 20 }, (_, i) => {
+      const o = { id: `id-${i}`, pad: 'p'.repeat(50) };
+      if (i % 5 === 0) o.x = i;
+      if (i % 7 === 0) o.y = i;
+      return o;
+    });
+    const input = JSON.stringify(arr);
+    const result = crusher.compress(input, null);
+    // Should not use lossless-csv (only 2 fields appear in all items, but id+pad=2 < 3)
+    // May be lossy-sample or passthrough depending on n vs maxItemsAfterCrush
+    if (result.compressed) {
+      expect(result.strategy).not.toBe('lossless-csv');
+    }
+  });
+});
+
+describe('SmartCrusher — lossy-sample path', () => {
+  let crusher;
+  let store;
+  beforeEach(() => {
+    crusher = new SmartCrusher();
+    store = new CcrStore(60); // 60s TTL for tests
+  });
+  afterEach(() => { store.destroy(); });
+
+  function makeSparseInput(n) {
+    // Only 'id' universal — no lossless-csv. Long enough to exceed 8000 chars.
+    const pad = 'x'.repeat(200);
+    return Array.from({ length: n }, (_, i) => {
+      const o = { id: `item-${String(i).padStart(5, '0')}` };
+      if (i % 2 === 0) o.payload = `pay_${i}_${pad}`;
+      if (i % 3 === 0) o.stage = 'active';
+      if (i % 4 === 0) o.value = i * 100;
+      if (i % 5 === 0) o.ts = `2026-06-${String((i % 28) + 1).padStart(2, '0')}`;
+      if (i % 6 === 0) o.owner = `rep-${i % 8}`;
+      if (i % 7 === 0) o.src = 'crm';
+      return o;
+    });
+  }
+
+  it('triggers lossy-sample when n > maxItemsAfterCrush (15) and lossless fails', () => {
+    const input = JSON.stringify(makeSparseInput(40));
+    const result = crusher.compress(input, store);
+    expect(result.compressed).toBe(true);
+    expect(result.strategy).toBe('lossy-sample');
+    expect(result.rowsDropped).toBeGreaterThan(0);
+  });
+
+  it('stores dropped rows in CCR store', () => {
+    const input = JSON.stringify(makeSparseInput(40));
+    const result = crusher.compress(input, store);
+    if (result.strategy !== 'lossy-sample') return;
+    expect(result.ccrHash).not.toBeNull();
+    const stored = store.get(result.ccrHash);
+    expect(stored).not.toBeNull();
+    const parsed = JSON.parse(stored);
+    expect(Array.isArray(parsed)).toBe(true);
+    expect(parsed.length).toBe(result.rowsDropped);
+  });
+
+  it('output contains CCR marker for dropped rows', () => {
+    const input = JSON.stringify(makeSparseInput(40));
+    const result = crusher.compress(input, store);
+    if (result.strategy !== 'lossy-sample') return;
+    expect(result.output).toContain('_ccr_dropped');
+    expect(result.output).toContain(result.ccrHash);
+  });
+
+  it('kept items include error-signaling items (score += 100)', () => {
+    // Items with 'error' or 'failed' values should be preserved
+    const items = makeSparseInput(40);
+    // Inject an error item in the middle
+    items[20] = { id: 'item-00020', status: '"error"', reason: 'timeout_exceeded' };
+    const input = JSON.stringify(items);
+    const result = crusher.compress(input, store);
+    if (result.strategy !== 'lossy-sample') return;
+    // The error item should be in the kept portion
+    expect(result.output).toContain('item-00020');
+  });
+
+  it('deletes CCR entry when savings < threshold', () => {
+    // Array just over maxItemsAfterCrush but with high savings already (lossless might win)
+    const tiny = JSON.stringify(makeSparseInput(16));
+    const result = crusher.compress(tiny, store);
+    // If no savings or passthrough, CCR store should not be polluted
+    if (!result.compressed) {
+      expect(result.ccrHash).toBeNull();
+    }
+  });
+});
+
+describe('SmartCrusher — DEFAULT_CRUSHER_CONFIG', () => {
+  it('exports expected default config values', () => {
+    expect(DEFAULT_CRUSHER_CONFIG.minItemsToAnalyze).toBe(5);
+    expect(DEFAULT_CRUSHER_CONFIG.minCharsToCompress).toBe(200);
+    expect(DEFAULT_CRUSHER_CONFIG.maxItemsAfterCrush).toBe(15);
+    expect(DEFAULT_CRUSHER_CONFIG.firstFraction).toBe(0.3);
+    expect(DEFAULT_CRUSHER_CONFIG.lastFraction).toBe(0.15);
+    expect(DEFAULT_CRUSHER_CONFIG.losslessMinSavingsRatio).toBe(0.15);
+    expect(DEFAULT_CRUSHER_CONFIG.compactionCoreFieldFraction).toBe(0.8);
+  });
+
+  it('allows config override via constructor', () => {
+    const custom = new SmartCrusher({ maxItemsAfterCrush: 5 });
+    // 8-item sparse array should now trigger lossy (>5) when lossless fails
+    const pad = 'x'.repeat(300);
+    const arr = Array.from({ length: 8 }, (_, i) => {
+      const o = { id: `x-${i}` };
+      if (i % 2 === 0) o.extra = `val_${i}_${pad}`;
+      return o;
+    });
+    const input = JSON.stringify(arr);
+    const result = custom.compress(input, new CcrStore(10));
+    // With maxItemsAfterCrush=5, 8 items should trigger lossy if lossless fails
+    if (result.compressed) {
+      expect(['lossless-csv', 'lossy-sample']).toContain(result.strategy);
+    }
+  });
+});

package/lib/compression/dist/server.js

@@ -150,9 +150,21 @@ async function handleDirectCompress(req, res) {
     const messages = body.messages;
     if (!Array.isArray(messages)) {
         stats.requests.passthrough++;
-        json(res, 200, { messages: body, tokensSaved: 0, compressionRatio: 1, transformsApplied: [], ccrHashes: [] });
+        // Passthrough — return both camelCase and snake_case for SDK compatibility
+        json(res, 200, {
+            messages: body,
+            // camelCase (direct-HTTP callers: context-compaction.ts, hema-dispatch-v3)
+            tokensSaved: 0, compressionRatio: 1, transformsApplied: [], ccrHashes: [],
+            // snake_case (headroom-ai SDK _doCompress reads data.tokens_saved etc.)
+            tokens_before: 0, tokens_after: 0, tokens_saved: 0,
+            compression_ratio: 1, transforms_applied: [], ccr_hashes: [],
+            compressed: false,
+        });
         return;
     }
+    // Estimate tokens_before from raw input length (same heuristic as ContentRouter: 3.5 chars/token)
+    const CHARS_PER_TOKEN = 3.5;
+    const tokensBefore = Math.ceil(JSON.stringify(messages).length / CHARS_PER_TOKEN);
     try {
         const result = pipeline.compress(messages, ccrStore);
         stats.tokens.saved += result.tokensSaved;
@@ -162,12 +174,33 @@ async function handleDirectCompress(req, res) {
             stats.requests.compressed++;
         else
             stats.requests.passthrough++;
+        const tokensAfter = Math.max(0, tokensBefore - result.tokensSaved);
+        const wasCompressed = result.transformsApplied.length > 0;
         json(res, 200, {
             messages: result.messages,
+            // ── camelCase fields ──────────────────────────────────────────────────
+            // Used by direct-HTTP callers: context-compaction.ts (applyHeadroomCompression),
+            // hema-dispatch-v3 (recall compress), helios-api (HBO response wrap).
+            // These callers read result.tokensSaved, result.compressionRatio, etc.
             tokensSaved: result.tokensSaved,
             compressionRatio: result.compressionRatio,
             transformsApplied: result.transformsApplied,
             ccrHashes: result.ccrHashes,
+            // ── snake_case fields ─────────────────────────────────────────────────
+            // Required by headroom-ai SDK v0.22.4 _doCompress():
+            //   data.tokens_before, data.tokens_after, data.tokens_saved,
+            //   data.compression_ratio, data.transforms_applied, data.ccr_hashes
+            // Used by SharedContext.put() to compute entry.savingsPercent and
+            // to set entry.compressed = true so the compressed content is stored.
+            tokens_before: tokensBefore,
+            tokens_after: tokensAfter,
+            tokens_saved: result.tokensSaved,
+            compression_ratio: result.compressionRatio,
+            transforms_applied: result.transformsApplied,
+            ccr_hashes: result.ccrHashes,
+            // compressed: true triggers SharedContext to store result.messages[0].content
+            // instead of falling back to the original uncompressed content.
+            compressed: wasCompressed,
         });
     }
     catch (e) {

package/lib/compression/dist/start-server.js

@@ -0,0 +1,77 @@
+'use strict';
+/**
+ * lib/compression/dist/start-server.js
+ *
+ * Standalone entry point for the Helios Compression Server.
+ * Used by:
+ *   - evals/harbor/test_compression.py (pytest fixture spawns this directly)
+ *   - Manual testing: node lib/compression/dist/start-server.js [--port <n>]
+ *   - npm run test:compression
+ *
+ * The daemon uses server.js via HeadroomProxyManager (daemon/lib/headroom-proxy-manager.js),
+ * which spawns server.js directly. This file is the test-friendly wrapper.
+ *
+ * On ready: emits {"event":"ready","port":<n>,"version":"1.0.0-helios"} to stdout.
+ * On EADDRINUSE: logs to stderr and exits with code 1.
+ * Responds to SIGTERM/SIGINT with graceful shutdown (not available on Windows — falls back).
+ *
+ * Cross-platform: no shell, no signal assumptions beyond try/catch.
+ */
+
+const { createCompressionServer } = require('./server.js');
+
+// ── Port resolution ───────────────────────────────────────────────────────────
+// Priority: --port <n> CLI arg > HEADROOM_PORT env > 8787 default
+
+function resolvePort() {
+  const args = process.argv.slice(2);
+  const portFlagIdx = args.indexOf('--port');
+  if (portFlagIdx !== -1 && args[portFlagIdx + 1]) {
+    const parsed = parseInt(args[portFlagIdx + 1], 10);
+    if (!isNaN(parsed) && parsed > 0 && parsed < 65536) return parsed;
+  }
+  if (process.env.HEADROOM_PORT) {
+    const parsed = parseInt(process.env.HEADROOM_PORT, 10);
+    if (!isNaN(parsed) && parsed > 0 && parsed < 65536) return parsed;
+  }
+  return 8787;
+}
+
+const port = resolvePort();
+const VERSION = '1.0.0-helios';
+
+// ── Start ─────────────────────────────────────────────────────────────────────
+
+const server = createCompressionServer();
+
+server.listen(port, '127.0.0.1', () => {
+  // Emit the ready signal that HeadroomProxyManager and the test fixture parse
+  process.stdout.write(JSON.stringify({ event: 'ready', port, version: VERSION }) + '\n');
+});
+
+server.on('error', (err) => {
+  if (err.code === 'EADDRINUSE') {
+    process.stderr.write(
+      `[compression-server] Port ${port} already in use. ` +
+      `Use --port <n> or set HEADROOM_PORT env var.\n`
+    );
+    process.exit(1);
+  }
+  // Other errors — re-throw to get a full stack trace
+  throw err;
+});
+
+// ── Graceful shutdown ─────────────────────────────────────────────────────────
+// SIGTERM and SIGINT not available on Windows — wrap in try.
+
+function shutdown(signal) {
+  process.stderr.write(`[compression-server] Received ${signal}, shutting down...\n`);
+  server.close(() => {
+    process.exit(0);
+  });
+  // Force exit after 3s if connections are held open
+  setTimeout(() => process.exit(0), 3000).unref();
+}
+
+try { process.on('SIGTERM', () => shutdown('SIGTERM')); } catch (_) {}
+try { process.on('SIGINT',  () => shutdown('SIGINT'));  } catch (_) {}

package/lib/event-bus.mts

@@ -46,7 +46,7 @@ interface EventMap {
     senderHandle: string;
     subject: string;
     snippet: string;
-    body: string;
+    // body intentionally excluded — PII (SEC-6)
     threadId: string;
     receivedAt: string;
     suggestedAction: string;