plumb-bridge 0.1.2 → 0.1.3

package/test/adapter-parse.test.ts

@@ -0,0 +1,328 @@
+// PLUMB — Adapter Unit Tests
+// parseLine fixtures for all adapters. No live CLIs needed — pure parse validation.
+
+import { describe, it, expect } from 'bun:test';
+import { EchoAdapter } from '../src/adapters/echo.ts';
+import { PiAdapter } from '../src/adapters/pi.ts';
+import { ClaudeAdapter } from '../src/adapters/claude.ts';
+import { CursorAdapter } from '../src/adapters/cursor.ts';
+import { OpenCodeAdapter } from '../src/adapters/opencode.ts';
+import { VenomAdapter } from '../src/adapters/venom.ts';
+import { GenericAdapter } from '../src/adapters/generic.ts';
+import { tryParseLine, extractContentText, textDelta, statusEvent, errorEvent } from '../src/adapters/stream-json.ts';
+
+// ── Shared stream-json utility tests ──────────────────────────────────────
+
+describe('stream-json utilities', () => {
+  it('tryParseLine: empty line → null json, empty raw', () => {
+    const result = tryParseLine('   ');
+    expect(result.json).toBeNull();
+    expect(result.raw).toBe('');
+  });
+
+  it('tryParseLine: non-JSON line → null json, raw preserved', () => {
+    const result = tryParseLine('hello world');
+    expect(result.json).toBeNull();
+    expect(result.raw).toBe('hello world');
+  });
+
+  it('tryParseLine: valid JSON → parsed object', () => {
+    const result = tryParseLine('{"type":"text","text":"hi"}');
+    expect(result.json).not.toBeNull();
+    expect(result.json!.type).toBe('text');
+  });
+
+  it('extractContentText: extracts text blocks from message.content', () => {
+    const event = {
+      type: 'assistant',
+      message: {
+        content: [
+          { type: 'text', text: 'Hello ' },
+          { type: 'text', text: 'World' },
+          { type: 'image', url: 'x' },
+        ],
+      },
+    };
+    expect(extractContentText(event)).toBe('Hello \nWorld');
+  });
+
+  it('extractContentText: returns null when no text content', () => {
+    const event = {
+      type: 'assistant',
+      message: { content: [{ type: 'image', url: 'x' }] },
+    };
+    expect(extractContentText(event)).toBeNull();
+  });
+
+  it('extractContentText: returns null when no message', () => {
+    expect(extractContentText({ type: 'assistant' })).toBeNull();
+  });
+
+  it('helper functions produce correct events', () => {
+    expect(textDelta('hi')).toEqual({ type: 'text-delta', text: 'hi' });
+    expect(statusEvent('completed')).toEqual({ type: 'status', state: 'completed' });
+    expect(errorEvent('fail')).toEqual({ type: 'error', message: 'fail' });
+    expect(errorEvent('fail', 'CODE')).toEqual({ type: 'error', message: 'fail', code: 'CODE' });
+  });
+});
+
+// ── Echo Adapter ───────────────────────────────────────────────────────────
+
+describe('EchoAdapter', () => {
+  const adapter = new EchoAdapter();
+
+  it('returns text-delta for each non-empty line', () => {
+    const events = adapter.parseLine('hello');
+    expect(events).toEqual([{ type: 'text-delta', text: 'hello\n' }]);
+  });
+
+  it('skips empty lines', () => {
+    expect(adapter.parseLine('   ')).toEqual([]);
+    expect(adapter.parseLine('')).toEqual([]);
+  });
+
+  it('formatInput appends newline', () => {
+    expect(adapter.formatInput({ id: '1', message: 'test' })).toBe('test\n');
+  });
+
+  it('buildArgs returns empty array', () => {
+    expect(adapter.buildArgs({ id: '1', message: 'test' }, { cli: 'cat', port: 3001 })).toEqual([]);
+  });
+});
+
+// ── Pi Adapter ────────────────────────────────────────────────────────────
+
+describe('PiAdapter', () => {
+  const adapter = new PiAdapter();
+
+  it('parses text-delta event', () => {
+    const events = adapter.parseLine(JSON.stringify({ type: 'text-delta', text: 'hello' }));
+    expect(events).toEqual([{ type: 'text-delta', text: 'hello' }]);
+  });
+
+  it('parses message_update with text_delta', () => {
+    const events = adapter.parseLine(JSON.stringify({
+      type: 'message_update',
+      assistantMessageEvent: { type: 'text_delta', delta: 'world' },
+    }));
+    expect(events).toEqual([{ type: 'text-delta', text: 'world' }]);
+  });
+
+  it('filters extension_ui_request events', () => {
+    expect(adapter.parseLine(JSON.stringify({ type: 'extension_ui_request' }))).toEqual([]);
+  });
+
+  it('parses agent_end as completed', () => {
+    const events = adapter.parseLine(JSON.stringify({ type: 'agent_end' }));
+    expect(events).toEqual([{ type: 'status', state: 'completed' }]);
+  });
+
+  it('parses error event', () => {
+    const events = adapter.parseLine(JSON.stringify({ type: 'error', error: 'test error' }));
+    expect(events).toEqual([{ type: 'error', message: 'test error' }]);
+  });
+
+  it('non-JSON line → raw text delta', () => {
+    const events = adapter.parseLine('raw text output');
+    expect(events).toEqual([{ type: 'text-delta', text: 'raw text output\n' }]);
+  });
+});
+
+// ── Claude Adapter ────────────────────────────────────────────────────────
+
+describe('ClaudeAdapter', () => {
+  const adapter = new ClaudeAdapter();
+
+  it('parses assistant message with text content', () => {
+    const events = adapter.parseLine(JSON.stringify({
+      type: 'assistant',
+      message: { content: [{ type: 'text', text: 'Hello Claude' }] },
+    }));
+    expect(events).toEqual([{ type: 'text-delta', text: 'Hello Claude' }]);
+  });
+
+  it('filters system and rate_limit events', () => {
+    expect(adapter.parseLine(JSON.stringify({ type: 'system' }))).toEqual([]);
+    expect(adapter.parseLine(JSON.stringify({ type: 'rate_limit_event' }))).toEqual([]);
+  });
+
+  it('parses successful result as completed', () => {
+    const events = adapter.parseLine(JSON.stringify({ type: 'result' }));
+    expect(events).toEqual([{ type: 'status', state: 'completed' }]);
+  });
+
+  it('parses error result', () => {
+    const events = adapter.parseLine(JSON.stringify({ type: 'result', is_error: true, error: 'fail' }));
+    expect(events).toEqual([{ type: 'error', message: 'fail' }]);
+  });
+
+  it('parses explicit error event', () => {
+    const events = adapter.parseLine(JSON.stringify({ type: 'error', error: 'bad' }));
+    expect(events).toEqual([{ type: 'error', message: 'bad' }]);
+  });
+});
+
+// ── Cursor Adapter ────────────────────────────────────────────────────────
+
+describe('CursorAdapter', () => {
+  const adapter = new CursorAdapter();
+
+  it('parses thinking event as text-delta', () => {
+    const events = adapter.parseLine(JSON.stringify({ type: 'thinking', text: 'reasoning...' }));
+    expect(events).toEqual([{ type: 'text-delta', text: 'reasoning...' }]);
+  });
+
+  it('parses assistant content blocks', () => {
+    const events = adapter.parseLine(JSON.stringify({
+      type: 'assistant',
+      message: { content: [{ type: 'text', text: 'code here' }] },
+    }));
+    expect(events).toEqual([{ type: 'text-delta', text: 'code here' }]);
+  });
+
+  it('filters system and user events', () => {
+    expect(adapter.parseLine(JSON.stringify({ type: 'system' }))).toEqual([]);
+    expect(adapter.parseLine(JSON.stringify({ type: 'user' }))).toEqual([]);
+  });
+
+  it('parses tool_call with shellToolCall', () => {
+    const events = adapter.parseLine(JSON.stringify({
+      type: 'tool_call',
+      tool_call: { shellToolCall: { args: { command: 'ls' } } },
+    }));
+    expect(events).toEqual([{ type: 'tool-call', tool: 'shell', input: { command: 'ls' } }]);
+  });
+
+  it('skips consolidated events when streamPartial=true', () => {
+    adapter.streamPartial = true;
+    // Consolidated event: no timestamp_ms
+    const events = adapter.parseLine(JSON.stringify({
+      type: 'assistant',
+      message: { content: [{ type: 'text', text: 'should skip' }] },
+    }));
+    expect(events).toEqual([]);
+    // Streaming delta: has timestamp_ms
+    const delta = adapter.parseLine(JSON.stringify({
+      type: 'assistant',
+      message: { content: [{ type: 'text', text: 'should emit' }] },
+      timestamp_ms: 1234,
+    }));
+    expect(delta).toEqual([{ type: 'text-delta', text: 'should emit' }]);
+    adapter.streamPartial = false; // reset
+  });
+
+  it('parses successful result as completed', () => {
+    expect(adapter.parseLine(JSON.stringify({ type: 'result' }))).toEqual([{ type: 'status', state: 'completed' }]);
+  });
+
+  it('parses error result', () => {
+    expect(adapter.parseLine(JSON.stringify({ type: 'result', subtype: 'error', error: 'crash' }))).toEqual([{ type: 'error', message: 'crash' }]);
+  });
+});
+
+// ── VENOM Adapter ──────────────────────────────────────────────────────────
+
+describe('VenomAdapter', () => {
+  const adapter = new VenomAdapter();
+
+  it('parses assistant content blocks', () => {
+    const events = adapter.parseLine(JSON.stringify({
+      type: 'assistant',
+      message: { content: [{ type: 'text', text: 'venom output' }] },
+      timestamp_ms: 100,
+    }));
+    expect(events).toEqual([{ type: 'text-delta', text: 'venom output' }]);
+  });
+
+  it('skips consolidated events (streamPartial=true by default)', () => {
+    // No timestamp_ms = consolidated → skip
+    expect(adapter.parseLine(JSON.stringify({
+      type: 'assistant',
+      message: { content: [{ type: 'text', text: 'skip' }] },
+    }))).toEqual([]);
+  });
+
+  it('parses successful result as completed', () => {
+    expect(adapter.parseLine(JSON.stringify({ type: 'result' }))).toEqual([{ type: 'status', state: 'completed' }]);
+  });
+
+  it('parses error event', () => {
+    expect(adapter.parseLine(JSON.stringify({ type: 'error', error: 'fail' }))).toEqual([{ type: 'error', message: 'fail' }]);
+  });
+
+  it('filters system and user events', () => {
+    expect(adapter.parseLine(JSON.stringify({ type: 'system' }))).toEqual([]);
+    expect(adapter.parseLine(JSON.stringify({ type: 'user' }))).toEqual([]);
+  });
+
+  it('parses tool_call with shellToolCall', () => {
+    const events = adapter.parseLine(JSON.stringify({
+      type: 'tool_call',
+      tool_call: { shellToolCall: { args: { cmd: 'cargo build' } } },
+    }));
+    expect(events).toEqual([{ type: 'tool-call', tool: 'shell', input: { cmd: 'cargo build' } }]);
+  });
+});
+
+// ── OpenCode Adapter ──────────────────────────────────────────────────────
+
+describe('OpenCodeAdapter', () => {
+  const adapter = new OpenCodeAdapter();
+
+  it('parses text event', () => {
+    const events = adapter.parseLine(JSON.stringify({ type: 'text', text: 'hello' }));
+    expect(events).toEqual([{ type: 'text-delta', text: 'hello' }]);
+  });
+
+  it('parses content event with text', () => {
+    const events = adapter.parseLine(JSON.stringify({ type: 'content', content: 'output' }));
+    expect(events).toEqual([{ type: 'text-delta', text: 'output' }]);
+  });
+
+  it('parses step_finish with stop reason as completed', () => {
+    const events = adapter.parseLine(JSON.stringify({ type: 'step_finish', part: { reason: 'stop' } }));
+    expect(events).toEqual([{ type: 'status', state: 'completed' }]);
+  });
+
+  it('parses done event as completed', () => {
+    expect(adapter.parseLine(JSON.stringify({ type: 'done' }))).toEqual([{ type: 'status', state: 'completed' }]);
+  });
+
+  it('parses session.completed as completed', () => {
+    expect(adapter.parseLine(JSON.stringify({ type: 'session.completed' }))).toEqual([{ type: 'status', state: 'completed' }]);
+  });
+
+  it('parses error event', () => {
+    expect(adapter.parseLine(JSON.stringify({ type: 'error', error: 'break' }))).toEqual([{ type: 'error', message: 'break' }]);
+  });
+
+  it('non-JSON line → raw text delta', () => {
+    const events = adapter.parseLine('plain text');
+    expect(events).toEqual([{ type: 'text-delta', text: 'plain text\n' }]);
+  });
+
+  it('formatInput wraps in JSON prompt', () => {
+    const input = adapter.formatInput({ id: '1', message: 'test prompt' });
+    expect(JSON.parse(input)).toEqual({ prompt: 'test prompt' });
+  });
+});
+
+// ── Generic Adapter ────────────────────────────────────────────────────────
+
+describe('GenericAdapter', () => {
+  it('returns text-delta for each non-empty line', () => {
+    const adapter = new GenericAdapter('cat');
+    const events = adapter.parseLine('anything');
+    expect(events).toEqual([{ type: 'text-delta', text: 'anything\n' }]);
+  });
+
+  it('skips empty lines', () => {
+    const adapter = new GenericAdapter('cat');
+    expect(adapter.parseLine('  ')).toEqual([]);
+  });
+
+  it('formatInput appends newline', () => {
+    const adapter = new GenericAdapter('cat');
+    expect(adapter.formatInput({ id: '1', message: 'hello' })).toBe('hello\n');
+  });
+});

package/test/persistent-process.test.ts

@@ -0,0 +1,56 @@
+// PLUMB — PersistentProcess Unit Tests
+// Validates waitUntilReady, ready-frame interception, crash rejection.
+
+import { describe, test, expect } from 'bun:test';
+import { PersistentProcess } from '../src/core/process.ts';
+
+describe('PersistentProcess', () => {
+  test('waitUntilReady resolves on { "type": "ready" } frame', async () => {
+    const pp = new PersistentProcess('echo', [], {});
+    // Manually inject a ready frame via routeLine (testing the signal path)
+    // We can't easily spawn a real process here, so we test the public API contract
+    // by verifying waitUntilReady rejects on timeout with no process
+    await expect(
+      pp.waitUntilReady(100),
+    ).rejects.toThrow('Timed out waiting for persistent agent ready frame');
+  });
+
+  test('isAlive returns false before ensure', () => {
+    const pp = new PersistentProcess('echo', [], {});
+    expect(pp.isAlive).toBe(false);
+  });
+
+  test('isAlive returns true after ensure with echo', async () => {
+    const pp = new PersistentProcess('echo', [], {});
+    await pp.ensure();
+    expect(pp.isAlive).toBe(true);
+    await pp.kill();
+    expect(pp.isAlive).toBe(false);
+  });
+
+  test('routeLine swallows ready frame, does not route to task handler', async () => {
+    const pp = new PersistentProcess('echo', [], {});
+    let handlerCalled = false;
+    pp.setLineHandler('test-task', () => { handlerCalled = true; });
+
+    // Simulate what routeLine does internally by checking that
+    // after ensure + kill cycle, the process was valid
+    await pp.ensure();
+    await pp.kill();
+    // If we could call routeLine directly we'd verify the ready frame is swallowed.
+    // Since routeLine is private, we verify via the integration test (conformance).
+    // Here we just confirm the process lifecycle works.
+    expect(pp.isAlive).toBe(false);
+  });
+
+  test('ensure is idempotent — second call returns immediately', async () => {
+    const pp = new PersistentProcess('sleep', ['60'], {});
+    const start = Date.now();
+    await pp.ensure();
+    await pp.ensure(); // should not spawn again
+    const elapsed = Date.now() - start;
+    expect(elapsed).toBeLessThan(2000);
+    expect(pp.isAlive).toBe(true);
+    await pp.kill();
+  });
+});

package/test/rpc.test.ts

@@ -0,0 +1,57 @@
+// PLUMB — RPC Unit Tests
+// Validates sendRpcCommand, response correlation, host tool execution, timeout.
+
+import { describe, test, expect, afterEach } from 'bun:test';
+import { PersistentProcess } from '../src/core/process.ts';
+import type { RpcHostToolExecutor } from '../src/types.ts';
+
+describe('PersistentProcess RPC', () => {
+  let proc: PersistentProcess;
+
+  afterEach(async () => {
+    await proc?.kill();
+  });
+
+  test('sendRpcCommand rejects when process is not alive', async () => {
+    proc = new PersistentProcess('echo', [], {});
+    expect(proc.isAlive).toBe(false);
+    await expect(proc.sendRpcCommand({ type: 'ping' })).rejects.toThrow('Persistent process is not alive');
+  });
+
+  test('sendRpcCommand times out when no response arrives', async () => {
+    proc = new PersistentProcess('cat', [], {});
+    await proc.ensure();
+    const result = await proc.sendRpcCommand({ type: 'ping' }, { timeoutMs: 200 });
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('RPC correlation timeout');
+  });
+
+  test('sendRpcCommand auto-assigns correlation id', async () => {
+    proc = new PersistentProcess('cat', [], {});
+    await proc.ensure();
+    // We can't easily test full correlation without a real echo agent,
+    // but we can verify the method doesn't throw for alive processes
+    // and the timeout path works with auto-assigned IDs.
+    const result = await proc.sendRpcCommand({ type: 'test' }, { timeoutMs: 100 });
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('test');
+  });
+
+  test('setHostToolExecutor and setRpcTimeoutMs are no-ops on dead process', () => {
+    proc = new PersistentProcess('echo', [], {});
+    const executor: RpcHostToolExecutor = async () => ({ content: [{ type: 'text', text: 'ok' }] });
+    expect(() => proc.setHostToolExecutor(executor)).not.toThrow();
+    expect(() => proc.setRpcTimeoutMs(5000)).not.toThrow();
+    expect(() => proc.setRpcTimeoutMs(0)).not.toThrow(); // clamped to 1000
+  });
+
+  test('host_tool_cancel does not throw without executor', async () => {
+    proc = new PersistentProcess('cat', [], {});
+    await proc.ensure();
+    // Sending a host_tool_cancel line to routeLine without an executor should not crash
+    // (routeLine handles it gracefully via dispatchProtocolFrame)
+    // We can't call routeLine directly (private), but we verify kill doesn't crash
+    await proc.kill();
+    expect(proc.isAlive).toBe(false);
+  });
+});

package/test/session-store.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect, beforeEach } from 'bun:test';
+import { CursorSessionStore } from '../src/core/session-store.ts';
+
+describe('CursorSessionStore', () => {
+  it('registers a new session and sets lastSession', () => {
+    const store = new CursorSessionStore();
+    store.register('s1', '/workspace', 'model-a');
+    expect(store.lastSession).toBe('s1');
+    const s = store.get('s1');
+    expect(s).toBeDefined();
+    expect(s!.id).toBe('s1');
+    expect(s!.workspace).toBe('/workspace');
+    expect(s!.model).toBe('model-a');
+    expect(s!.turnCount).toBe(1);
+    expect(s!.turns).toHaveLength(0);
+  });
+
+  it('increments turnCount on re-register', () => {
+    const store = new CursorSessionStore();
+    store.register('s1', '/w', 'm');
+    store.register('s1', '/w', 'm');
+    expect(store.get('s1')!.turnCount).toBe(2);
+    expect(store.lastSession).toBe('s1');
+  });
+
+  it('records completed turns with truncation', () => {
+    const store = new CursorSessionStore({ recapMaxTurns: 2, recapMaxCharsPerLeg: 20 });
+    store.register('s1', '/w', 'm');
+    store.recordCompletedTurn('s1', 'hello', 'world');
+    store.recordCompletedTurn('s1', 'msg2', 'resp2');
+    store.recordCompletedTurn('s1', 'msg3', 'resp3'); // should evict msg1
+    const s = store.get('s1')!;
+    expect(s.turns).toHaveLength(2);
+    expect(s.turns[0]!.user).toBe('msg2');
+    expect(s.turns[1]!.user).toBe('msg3');
+  });
+
+  it('expireLastSessionIfStale drops session and queues recap when turns exist', () => {
+    const store = new CursorSessionStore({ sessionTtlMs: 60_000 });
+    store.register('s1', '/w', 'm');
+    store.recordCompletedTurn('s1', 'user says', 'assistant says');
+    // Backdate lastUsedAt to 2 minutes ago
+    const s = store.get('s1')!;
+    s.lastUsedAt = new Date(Date.now() - 120_000);
+    store.expireLastSessionIfStale();
+    expect(store.lastSession).toBeNull();
+    expect(store.get('s1')).toBeUndefined();
+    const recap = store.consumeColdRecap();
+    expect(recap).toContain('user says');
+    expect(recap).toContain('assistant says');
+  });
+
+  it('expireLastSessionIfStale clears stale session without recap when no turns', () => {
+    const store = new CursorSessionStore({ sessionTtlMs: 1000 });
+    store.register('s1', '/w', 'm');
+    const s = store.get('s1')!;
+    s.lastUsedAt = new Date(Date.now() - 5000);
+    store.expireLastSessionIfStale();
+    expect(store.lastSession).toBeNull();
+    expect(store.consumeColdRecap()).toBeNull();
+  });
+
+  it('consumeColdRecap returns null on second call', () => {
+    const store = new CursorSessionStore({ sessionTtlMs: 1000 });
+    store.register('s1', '/w', 'm');
+    store.recordCompletedTurn('s1', 'q', 'a');
+    const s = store.get('s1')!;
+    s.lastUsedAt = new Date(Date.now() - 5000);
+    store.expireLastSessionIfStale();
+    expect(store.consumeColdRecap()).not.toBeNull();
+    expect(store.consumeColdRecap()).toBeNull();
+  });
+
+  it('does not expire when within TTL', () => {
+    const store = new CursorSessionStore({ sessionTtlMs: 300_000 });
+    store.register('s1', '/w', 'm');
+    store.expireLastSessionIfStale();
+    expect(store.lastSession).toBe('s1');
+  });
+
+  it('does not expire when TTL is null', () => {
+    const store = new CursorSessionStore({ sessionTtlMs: null });
+    store.register('s1', '/w', 'm');
+    const s = store.get('s1')!;
+    s.lastUsedAt = new Date(Date.now() - 1_000_000);
+    store.expireLastSessionIfStale();
+    expect(store.lastSession).toBe('s1');
+  });
+
+  it('clear resets everything', () => {
+    const store = new CursorSessionStore({ sessionTtlMs: 1000 });
+    store.register('s1', '/w', 'm');
+    store.recordCompletedTurn('s1', 'q', 'a');
+    const s = store.get('s1')!;
+    s.lastUsedAt = new Date(Date.now() - 5000);
+    store.expireLastSessionIfStale();
+    store.clear();
+    expect(store.lastSession).toBeNull();
+    expect(store.list()).toHaveLength(0);
+    expect(store.consumeColdRecap()).toBeNull();
+  });
+
+  it('list returns sessions sorted by lastUsedAt desc', () => {
+    const store = new CursorSessionStore();
+    store.register('s1', '/w', 'm');
+    // Advance time by ensuring a real delay or manual backdate
+    const s1 = store.get('s1')!;
+    s1.lastUsedAt = new Date(Date.now() - 1000);
+    store.register('s2', '/w2', 'm2');
+    const list = store.list();
+    expect(list).toHaveLength(2);
+    expect(list[0]!.id).toBe('s2'); // most recent first
+    expect(list[1]!.id).toBe('s1');
+  });
+
+  it('recordCompletedTurn ignores null sessionId', () => {
+    const store = new CursorSessionStore();
+    store.register('s1', '/w', 'm');
+    // Should not throw
+    store.recordCompletedTurn(null, 'q', 'a');
+    expect(store.get('s1')!.turns).toHaveLength(0);
+  });
+
+  it('recordCompletedTurn ignores unknown sessionId', () => {
+    const store = new CursorSessionStore();
+    store.recordCompletedTurn('nonexistent', 'q', 'a');
+    expect(store.list()).toHaveLength(0);
+  });
+});

package/test/task-store.test.ts

@@ -0,0 +1,95 @@
+// PLUMB — Task Store Unit Tests
+// Validates LRU eviction, TTL cleanup, terminal state tracking.
+
+import { describe, test, expect, beforeEach } from 'bun:test';
+import { PlumbTaskStore } from '../src/core/task-store.ts';
+import type { Task } from '@a2a-js/sdk';
+
+function makeTask(id: string, state: string): Task {
+  return {
+    id,
+    contextId: id,
+    kind: 'task' as const,
+    status: { state, timestamp: new Date().toISOString() },
+    history: [],
+    artifacts: [],
+  } as Task;
+}
+
+describe('PlumbTaskStore', () => {
+  let store: PlumbTaskStore;
+
+  beforeEach(() => {
+    store = new PlumbTaskStore({ maxTasks: 5, completedRetentionMinutes: 0 });
+  });
+
+  test('save and load', async () => {
+    const task = makeTask('t1', 'working');
+    await store.save(task);
+    const loaded = await store.load('t1');
+    expect(loaded).not.toBeUndefined();
+    expect(loaded!.id).toBe('t1');
+    expect(loaded!.status.state).toBe('working');
+  });
+
+  test('load missing returns undefined', async () => {
+    const result = await store.load('nonexistent');
+    expect(result).toBeUndefined();
+  });
+
+  test('delete removes task', async () => {
+    const task = makeTask('t1', 'working');
+    await store.save(task);
+    await store.delete('t1');
+    const loaded = await store.load('t1');
+    expect(loaded).toBeUndefined();
+  });
+
+  test('LRU evicts terminal tasks first', async () => {
+    const small = new PlumbTaskStore({ maxTasks: 3 });
+    // Fill with terminal tasks
+    for (let i = 0; i < 4; i++) {
+      await small.save(makeTask(`t${i}`, 'completed'));
+    }
+    // Oldest terminal should be evicted
+    const t0 = await small.load('t0');
+    expect(t0).toBeUndefined();
+    // Newer tasks still present
+    const t3 = await small.load('t3');
+    expect(t3).not.toBeUndefined();
+  });
+
+  test('LRU prefers evicting terminal over active tasks', async () => {
+    const small = new PlumbTaskStore({ maxTasks: 3 });
+    await small.save(makeTask('a', 'completed'));
+    await small.save(makeTask('b', 'completed'));
+    await small.save(makeTask('c', 'working')); // active
+    // Force eviction by adding a 4th
+    await small.save(makeTask('d', 'completed'));
+    // 'a' (terminal) should be evicted, not 'c' (active)
+    expect(await small.load('a')).toBeUndefined();
+    expect(await small.load('c')).not.toBeUndefined();
+  });
+
+  test('cleanupStaleCompleted removes old terminal tasks', () => {
+    const storeWithRetention = new PlumbTaskStore({ maxTasks: 5, completedRetentionMinutes: 1 });
+    const task = makeTask('old', 'completed');
+    storeWithRetention.save(task);
+    // Force entry to have old terminal timestamp by manipulating internals
+    // @ts-expect-error — accessing private for test
+    const entry = storeWithRetention.entries.get('old');
+    if (entry) entry.terminalSinceMs = Date.now() - 120_000; // 2 min ago
+    storeWithRetention.cleanupStaleCompleted();
+    expect(storeWithRetention.size).toBe(0);
+  });
+
+  test('size reflects stored count', async () => {
+    expect(store.size).toBe(0);
+    await store.save(makeTask('a', 'working'));
+    expect(store.size).toBe(1);
+    await store.save(makeTask('b', 'completed'));
+    expect(store.size).toBe(2);
+    await store.delete('a');
+    expect(store.size).toBe(1);
+  });
+});

package/tsconfig.json

@@ -14,5 +14,5 @@
     "noFallthroughCasesInSwitch": true
   },
   "include": ["src/**/*.ts", "test/**/*.ts"],
-  "exclude": ["node_modules", "playgorund"]
+  "exclude": ["node_modules", "playground"]
 }