@flowcodex/core 0.3.0

package/tests/session-store.test.ts

@@ -0,0 +1,429 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fsp } from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  DefaultSessionStore,
+  generateSessionId,
+  projectHash,
+  flowcodexHome,
+  sessionsDir,
+  reconstructMessages,
+} from '../src/session/session-store.js';
+import type { SessionEvent } from '../src/session/types.js';
+
+let tmpDir: string;
+let sessionDir: string;
+
+describe('DefaultSessionStore', () => {
+  beforeEach(async () => {
+    tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'fcx-session-'));
+    sessionDir = path.join(tmpDir, 'sessions');
+    await fsp.mkdir(sessionDir, { recursive: true });
+  });
+  afterEach(async () => {
+    await fsp.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('generates a valid session ID', () => {
+    const id = generateSessionId(new Date('2026-06-20T12:30:45Z'), 'claude-sonnet-4-6');
+    expect(id).toContain('2026-06-20');
+    expect(id).toContain('12-30-45Z');
+    expect(id).toContain('claude-sonnet-4-6');
+    expect(id.split('/')).toHaveLength(2);
+  });
+
+  it('generates session ID without model', () => {
+    const id = generateSessionId(new Date('2026-06-20T12:30:45Z'));
+    expect(id).toContain('2026-06-20');
+    expect(id).not.toContain('claude');
+  });
+
+  it('appends and reads events', async () => {
+    const store = new DefaultSessionStore({ dir: sessionDir, model: 'test-model' });
+    const events: SessionEvent[] = [
+      {
+        type: 'session_start',
+        ts: new Date().toISOString(),
+        id: store.sessionId,
+        model: 'test-model',
+        cwd: tmpDir,
+      },
+      { type: 'user_input', ts: new Date().toISOString(), content: 'hello world' },
+    ];
+    for (const ev of events) {
+      await store.append(ev);
+    }
+    const read = await store.readAll();
+    expect(read).toHaveLength(2);
+    expect(read[0]?.type).toBe('session_start');
+    expect(read[1]?.type).toBe('user_input');
+  });
+
+  it('reads empty for missing file', async () => {
+    const store = new DefaultSessionStore({ dir: sessionDir });
+    const read = await store.readAll();
+    expect(read).toHaveLength(0);
+  });
+
+  it('close writes session_end event', async () => {
+    const store = new DefaultSessionStore({ dir: sessionDir });
+    await store.append({
+      type: 'session_start',
+      ts: new Date().toISOString(),
+      id: store.sessionId,
+      model: 'm',
+      cwd: tmpDir,
+    });
+    await store.close('normal');
+    const read = await store.readAll();
+    expect(read).toHaveLength(2);
+    expect(read[1]?.type).toBe('session_end');
+  });
+
+  it('close is idempotent', async () => {
+    const store = new DefaultSessionStore({ dir: sessionDir });
+    await store.close('normal');
+    await store.close('aborted');
+    const read = await store.readAll();
+    expect(read).toHaveLength(1);
+  });
+
+  it('does not append after close', async () => {
+    const store = new DefaultSessionStore({ dir: sessionDir });
+    await store.close('normal');
+    await store.append({ type: 'user_input', ts: new Date().toISOString(), content: 'late' });
+    const read = await store.readAll();
+    expect(read).toHaveLength(1);
+  });
+
+  it('scrubs secrets in user_input', async () => {
+    const store = new DefaultSessionStore({ dir: sessionDir });
+    const secret = 'sk-ant-api03-' + 'a'.repeat(95);
+    await store.append({
+      type: 'user_input',
+      ts: new Date().toISOString(),
+      content: `key=${secret}`,
+    });
+    const read = await store.readAll();
+    const content = read[0] as Extract<SessionEvent, { type: 'user_input' }>;
+    expect(typeof content.content === 'string' ? content.content : '').not.toContain(secret);
+    expect(typeof content.content === 'string' ? content.content : '').toContain('[REDACTED');
+  });
+
+  it('handles in_flight markers', async () => {
+    const store = new DefaultSessionStore({ dir: sessionDir });
+    await store.append({
+      type: 'in_flight_start',
+      ts: new Date().toISOString(),
+      kind: 'tool_batch',
+    });
+    await store.append({ type: 'in_flight_end', ts: new Date().toISOString(), kind: 'tool_batch' });
+    const read = await store.readAll();
+    expect(read).toHaveLength(2);
+    expect(read[0]?.type).toBe('in_flight_start');
+    expect(read[1]?.type).toBe('in_flight_end');
+  });
+
+  it('handles all event types', async () => {
+    const store = new DefaultSessionStore({ dir: sessionDir });
+    const events: SessionEvent[] = [
+      { type: 'session_start', ts: '2026-01-01T00:00:00Z', id: 'test', model: 'm', cwd: '/tmp' },
+      { type: 'user_input', ts: '2026-01-01T00:00:01Z', content: 'hi' },
+      { type: 'llm_request', ts: '2026-01-01T00:00:02Z', model: 'm', messageCount: 1 },
+      {
+        type: 'llm_response',
+        ts: '2026-01-01T00:00:03Z',
+        content: [{ type: 'text', text: 'hello' }],
+        stopReason: 'end_turn',
+        usage: { inputTokens: 10, outputTokens: 5 },
+      },
+      {
+        type: 'tool_use',
+        ts: '2026-01-01T00:00:04Z',
+        name: 'read',
+        id: 'tu1',
+        input: { path: 'test.ts' },
+      },
+      {
+        type: 'tool_result',
+        ts: '2026-01-01T00:00:05Z',
+        id: 'tu1',
+        content: 'file contents',
+        isError: false,
+      },
+      { type: 'ctx_pct', ts: '2026-01-01T00:00:06Z', pct: 0.5 },
+      { type: 'checkpoint', ts: '2026-01-01T00:00:07Z' },
+      { type: 'error', ts: '2026-01-01T00:00:08Z', error: 'something went wrong' },
+      { type: 'session_end', ts: '2026-01-01T00:00:09Z', reason: 'normal' },
+    ];
+    for (const ev of events) {
+      await store.append(ev);
+    }
+    const read = await store.readAll();
+    expect(read).toHaveLength(events.length);
+  });
+
+  it('skips corrupt lines on read', async () => {
+    const store = new DefaultSessionStore({ dir: sessionDir });
+    await store.append({ type: 'user_input', ts: new Date().toISOString(), content: 'good' });
+    await fsp.appendFile(store.filePath, 'this is not valid JSON\n', 'utf8');
+    await store.append({ type: 'user_input', ts: new Date().toISOString(), content: 'good2' });
+    const read = await store.readAll();
+    expect(read).toHaveLength(2);
+  });
+});
+
+describe('path helpers', () => {
+  it('projectHash is deterministic and 12 chars', () => {
+    const h1 = projectHash('/home/user/project');
+    const h2 = projectHash('/home/user/project');
+    expect(h1).toBe(h2);
+    expect(h1).toHaveLength(12);
+  });
+
+  it('projectHash differs for different paths', () => {
+    const h1 = projectHash('/home/user/project-a');
+    const h2 = projectHash('/home/user/project-b');
+    expect(h1).not.toBe(h2);
+  });
+
+  it('flowcodexHome respects FLOWCODEX_HOME', () => {
+    const prev = process.env.FLOWCODEX_HOME;
+    process.env.FLOWCODEX_HOME = '/custom/home';
+    expect(flowcodexHome()).toBe('/custom/home');
+    process.env.FLOWCODEX_HOME = prev;
+  });
+
+  it('sessionsDir includes project hash', () => {
+    const dir = sessionsDir('/my/project');
+    expect(dir).toContain('projects');
+    expect(dir).toContain('sessions');
+    expect(dir).toContain(projectHash('/my/project'));
+  });
+});
+
+describe('writeSummary on close', () => {
+  let tmpDir: string;
+  let sessionDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'fcx-summary-'));
+    sessionDir = path.join(tmpDir, 'sessions');
+    await fsp.mkdir(sessionDir, { recursive: true });
+  });
+  afterEach(async () => {
+    await fsp.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('writes summary.json on close', async () => {
+    const store = new DefaultSessionStore({ dir: sessionDir, model: 'test-model' });
+    store.setSummaryStats({
+      provider: 'anthropic',
+      totalTokens: 100,
+      totalCost: 0.5,
+      iterations: 3,
+    });
+    await store.append({
+      type: 'session_start',
+      ts: '2026-06-20T10:00:00Z',
+      id: store.sessionId,
+      model: 'test-model',
+      cwd: tmpDir,
+    });
+    await store.append({
+      type: 'user_input',
+      ts: '2026-06-20T10:00:01Z',
+      content: 'Hello world this is a test prompt',
+    });
+    await store.append({
+      type: 'tool_use',
+      ts: '2026-06-20T10:00:02Z',
+      name: 'read',
+      id: 'tu1',
+      input: { path: 'a.ts' },
+    });
+    await store.append({
+      type: 'tool_result',
+      ts: '2026-06-20T10:00:03Z',
+      id: 'tu1',
+      content: 'ok',
+      isError: false,
+    });
+    await store.close('normal');
+
+    const summaryPath = store.filePath.replace(/\.jsonl$/, '.summary.json');
+    const raw = await fsp.readFile(summaryPath, 'utf8');
+    const summary = JSON.parse(raw);
+    expect(summary.id).toBe(store.sessionId);
+    expect(summary.model).toBe('test-model');
+    expect(summary.provider).toBe('anthropic');
+    expect(summary.title).toContain('Hello world');
+    expect(summary.messageCount).toBe(1);
+    expect(summary.toolCallCount).toBe(1);
+    expect(summary.toolErrorCount).toBe(0);
+    expect(summary.totalTokens).toBe(100);
+    expect(summary.totalCost).toBe(0.5);
+    expect(summary.iterationCount).toBe(3);
+    expect(summary.outcome).toBe('completed');
+  });
+
+  it('close with error reason sets outcome to error', async () => {
+    const store = new DefaultSessionStore({ dir: sessionDir });
+    await store.append({
+      type: 'session_start',
+      ts: '2026-06-20T10:00:00Z',
+      id: store.sessionId,
+      model: 'm',
+      cwd: tmpDir,
+    });
+    await store.close('error');
+    const summaryPath = store.filePath.replace(/\.jsonl$/, '.summary.json');
+    const summary = JSON.parse(await fsp.readFile(summaryPath, 'utf8'));
+    expect(summary.outcome).toBe('error');
+  });
+
+  it('truncates title to 50 chars', async () => {
+    const store = new DefaultSessionStore({ dir: sessionDir });
+    await store.append({
+      type: 'session_start',
+      ts: '2026-06-20T10:00:00Z',
+      id: store.sessionId,
+      model: 'm',
+      cwd: tmpDir,
+    });
+    const longText = 'A'.repeat(100);
+    await store.append({ type: 'user_input', ts: '2026-06-20T10:00:01Z', content: longText });
+    await store.close('normal');
+    const summaryPath = store.filePath.replace(/\.jsonl$/, '.summary.json');
+    const summary = JSON.parse(await fsp.readFile(summaryPath, 'utf8'));
+    expect(summary.title.length).toBe(50);
+  });
+});
+
+describe('listSessions', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'fcx-list-'));
+  });
+  afterEach(async () => {
+    await fsp.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('returns empty array when no sessions', async () => {
+    process.env.FLOWCODEX_HOME = tmpDir;
+    const summaries = await DefaultSessionStore.listSessions('/fake/project');
+    expect(summaries).toEqual([]);
+  });
+
+  it('lists sessions from summary.json files', async () => {
+    process.env.FLOWCODEX_HOME = tmpDir;
+    const store = new DefaultSessionStore({ dir: sessionsDir('/p'), model: 'm' });
+    await fsp.mkdir(path.dirname(store.filePath), { recursive: true });
+    await store.append({
+      type: 'session_start',
+      ts: '2026-06-20T10:00:00Z',
+      id: store.sessionId,
+      model: 'm',
+      cwd: '/p',
+    });
+    await store.append({ type: 'user_input', ts: '2026-06-20T10:00:01Z', content: 'test' });
+    await store.close('normal');
+
+    const summaries = await DefaultSessionStore.listSessions('/p');
+    expect(summaries.length).toBeGreaterThanOrEqual(1);
+  });
+});
+
+describe('deleteSession', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'fcx-del-'));
+    process.env.FLOWCODEX_HOME = tmpDir;
+  });
+  afterEach(async () => {
+    await fsp.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('deletes jsonl and summary.json', async () => {
+    const store = await DefaultSessionStore.create('/p', 'm');
+    await store.append({
+      type: 'session_start',
+      ts: '2026-06-20T10:00:00Z',
+      id: store.sessionId,
+      model: 'm',
+      cwd: '/p',
+    });
+    await store.close('normal');
+
+    const suffix = store.sessionId.slice(-4);
+    await DefaultSessionStore.deleteSession('/p', suffix);
+
+    const after = await DefaultSessionStore.listSessions('/p');
+    expect(after).toEqual([]);
+  });
+});
+
+describe('reconstructMessages', () => {
+  it('reconstructs user and assistant messages', () => {
+    const events: SessionEvent[] = [
+      { type: 'user_input', ts: '2026-01-01T00:00:00Z', content: 'hello' },
+      {
+        type: 'llm_response',
+        ts: '2026-01-01T00:00:01Z',
+        content: [{ type: 'text', text: 'hi there' }],
+        stopReason: 'end_turn',
+        usage: { input: 1, output: 1 },
+      },
+    ];
+    const msgs = reconstructMessages(events);
+    expect(msgs).toHaveLength(2);
+    expect(msgs[0]?.role).toBe('user');
+    expect(msgs[1]?.role).toBe('assistant');
+  });
+
+  it('reconstructs tool_use and tool_result pairs', () => {
+    const events: SessionEvent[] = [
+      { type: 'user_input', ts: '2026-01-01T00:00:00Z', content: 'run tool' },
+      {
+        type: 'tool_use',
+        ts: '2026-01-01T00:00:01Z',
+        name: 'read',
+        id: 'tu1',
+        input: { path: 'a.ts' },
+      },
+      {
+        type: 'tool_result',
+        ts: '2026-01-01T00:00:02Z',
+        id: 'tu1',
+        content: 'file content',
+        isError: false,
+      },
+      {
+        type: 'llm_response',
+        ts: '2026-01-01T00:00:03Z',
+        content: [{ type: 'text', text: 'done' }],
+        stopReason: 'end_turn',
+        usage: { input: 1, output: 1 },
+      },
+    ];
+    const msgs = reconstructMessages(events);
+    expect(msgs).toHaveLength(4);
+    expect(msgs[0]?.role).toBe('user');
+    expect(msgs[1]?.role).toBe('assistant');
+    expect(msgs[2]?.role).toBe('user');
+    expect(msgs[3]?.role).toBe('assistant');
+  });
+
+  it('skips non-message events', () => {
+    const events: SessionEvent[] = [
+      { type: 'session_start', ts: '2026-01-01T00:00:00Z', id: 's1', model: 'm', cwd: '/p' },
+      { type: 'in_flight_start', ts: '2026-01-01T00:00:01Z', kind: 'tool_batch' },
+      { type: 'session_end', ts: '2026-01-01T00:00:02Z', reason: 'normal' },
+    ];
+    const msgs = reconstructMessages(events);
+    expect(msgs).toHaveLength(0);
+  });
+});

package/tests/ssrf-guard.test.ts

@@ -0,0 +1,112 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { isPrivateIp } from '../src/utils/ssrf-guard.js';
+
+describe('isPrivateIp', () => {
+  it('blocks 10.x.x.x', () => {
+    expect(isPrivateIp('10.0.0.1')).toBe(true);
+    expect(isPrivateIp('10.255.255.255')).toBe(true);
+  });
+  it('blocks 172.16-31.x.x', () => {
+    expect(isPrivateIp('172.16.0.1')).toBe(true);
+    expect(isPrivateIp('172.31.255.255')).toBe(true);
+  });
+  it('does not block 172.15 or 172.32', () => {
+    expect(isPrivateIp('172.15.0.1')).toBe(false);
+    expect(isPrivateIp('172.32.0.1')).toBe(false);
+  });
+  it('blocks 192.168.x.x', () => {
+    expect(isPrivateIp('192.168.1.1')).toBe(true);
+    expect(isPrivateIp('192.168.0.0')).toBe(true);
+  });
+  it('blocks 127.x.x.x loopback', () => {
+    expect(isPrivateIp('127.0.0.1')).toBe(true);
+    expect(isPrivateIp('127.1.2.3')).toBe(true);
+  });
+  it('blocks 169.254.x.x link-local/IMDS', () => {
+    expect(isPrivateIp('169.254.169.254')).toBe(true);
+  });
+  it('blocks 0.x.x.x unspecified', () => {
+    expect(isPrivateIp('0.0.0.0')).toBe(true);
+  });
+  it('allows public IPv4', () => {
+    expect(isPrivateIp('8.8.8.8')).toBe(false);
+    expect(isPrivateIp('1.1.1.1')).toBe(false);
+    expect(isPrivateIp('93.184.216.34')).toBe(false);
+  });
+  it('blocks IPv6 loopback ::1', () => {
+    expect(isPrivateIp('::1')).toBe(true);
+  });
+  it('blocks IPv6 ULA fc/fd', () => {
+    expect(isPrivateIp('fc00::1')).toBe(true);
+    expect(isPrivateIp('fd00::1')).toBe(true);
+    expect(isPrivateIp('fd12:3456:789a::1')).toBe(true);
+  });
+  it('blocks IPv6 link-local fe80::/10', () => {
+    expect(isPrivateIp('fe80::1')).toBe(true);
+    expect(isPrivateIp('fe90::1')).toBe(true);
+    expect(isPrivateIp('febf::1')).toBe(true);
+    expect(isPrivateIp('fec0::1')).toBe(false);
+  });
+  it('allows public IPv6', () => {
+    expect(isPrivateIp('2001:4860:4860::8888')).toBe(false);
+  });
+  it('handles invalid IP strings', () => {
+    expect(isPrivateIp('not-an-ip')).toBe(false);
+    expect(isPrivateIp('')).toBe(false);
+    expect(isPrivateIp('999.999.999.999')).toBe(false);
+  });
+});
+
+describe('safeFetch with allow-private', () => {
+  const prevAllow = process.env.FLOWCODEX_FETCH_ALLOW_PRIVATE;
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    if (prevAllow !== undefined) {
+      process.env.FLOWCODEX_FETCH_ALLOW_PRIVATE = prevAllow;
+    } else {
+      delete process.env.FLOWCODEX_FETCH_ALLOW_PRIVATE;
+    }
+  });
+
+  it('fetches when allow-private bypass is set', async () => {
+    process.env.FLOWCODEX_FETCH_ALLOW_PRIVATE = '1';
+    globalThis.fetch = (() =>
+      Promise.resolve(new Response('hello', { status: 200 }))) as typeof fetch;
+    const { safeFetch } = await import('../src/utils/ssrf-guard.js');
+    const res = await safeFetch('http://example.com/test');
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe('hello');
+  });
+
+  it('follows redirects under allow-private', async () => {
+    process.env.FLOWCODEX_FETCH_ALLOW_PRIVATE = '1';
+    let calls = 0;
+    globalThis.fetch = ((input: RequestInfo | URL) => {
+      calls++;
+      const url = typeof input === 'string' ? input : input.toString();
+      if (url.includes('/redirect')) {
+        return Promise.resolve(
+          new Response(null, { status: 302, headers: { location: 'http://example.com/final' } }),
+        );
+      }
+      return Promise.resolve(new Response('final', { status: 200 }));
+    }) as typeof fetch;
+    const { safeFetch } = await import('../src/utils/ssrf-guard.js');
+    const res = await safeFetch('http://example.com/redirect');
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe('final');
+    expect(calls).toBe(2);
+  });
+
+  it('throws WEBFETCH_FAILED on too many redirects', async () => {
+    process.env.FLOWCODEX_FETCH_ALLOW_PRIVATE = '1';
+    globalThis.fetch = (() =>
+      Promise.resolve(
+        new Response(null, { status: 302, headers: { location: 'http://example.com/loop' } }),
+      )) as typeof fetch;
+    const { safeFetch } = await import('../src/utils/ssrf-guard.js');
+    await expect(safeFetch('http://example.com/loop', { maxRedirects: 2 })).rejects.toThrow();
+  });
+});

package/tests/system-prompt-builder.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import { DefaultSystemPromptBuilder, IDENTITY_PROMPT } from '../src/agent/system-prompt-builder.js';
+import type { Tool } from '../src/types/tool.js';
+import type { TextBlock } from '../src/types/blocks.js';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+function makeTool(name: string, usageHint?: string): Tool {
+  return {
+    name,
+    description: usageHint ? '' : `description for ${name}`,
+    usageHint,
+    inputSchema: { type: 'object' },
+    permission: 'auto',
+    mutating: false,
+    async execute() {
+      return 'ok';
+    },
+  };
+}
+
+const tmpRoot = os.tmpdir();
+
+function ctx(overrides: Partial<Parameters<DefaultSystemPromptBuilder['build']>[0]> = {}) {
+  return {
+    tools: [makeTool('read', 'Read a file.'), makeTool('bash', 'Run a shell command.')] as readonly Tool[],
+    model: { provider: 'anthropic', model: 'claude-sonnet-4-6' },
+    projectRoot: tmpRoot,
+    cwd: tmpRoot,
+    tokenSavingMode: false,
+    ...overrides,
+  };
+}
+
+describe('DefaultSystemPromptBuilder', () => {
+  it('builds exactly 3 layers when no AGENTS.md (identity, tools, env)', async () => {
+    const b = new DefaultSystemPromptBuilder();
+    const blocks = await b.build(ctx({ projectRoot: path.join(tmpRoot, 'no-such-agents-md-dir') }));
+    expect(blocks).toHaveLength(3);
+    expect(blocks.every((bl) => bl.type === 'text')).toBe(true);
+  });
+
+  it('layer 1 is the identity prompt', async () => {
+    const b = new DefaultSystemPromptBuilder();
+    const blocks = await b.build(ctx());
+    expect((blocks[0] as TextBlock).text).toBe(IDENTITY_PROMPT);
+  });
+
+  it('layer 2 lists tools with usageHint ?? description', async () => {
+    const b = new DefaultSystemPromptBuilder();
+    const blocks = await b.build(ctx());
+    const toolsText = (blocks[1] as TextBlock).text;
+    expect(toolsText).toContain('- read:');
+    expect(toolsText).toContain('Read a file.');
+    expect(toolsText).toContain('- bash:');
+  });
+
+  it('trims usageHint to 80 chars in normal mode', async () => {
+    const long = 'x'.repeat(120);
+    const b = new DefaultSystemPromptBuilder();
+    const blocks = await b.build(ctx({ tools: [makeTool('bigtool', long)] }));
+    const toolsText = (blocks[1] as TextBlock).text;
+    expect(toolsText).toContain('x'.repeat(80));
+    expect(toolsText).not.toContain('x'.repeat(81));
+  });
+
+  it('trims usageHint to 60 chars in token-saving mode', async () => {
+    const long = 'y'.repeat(120);
+    const b = new DefaultSystemPromptBuilder();
+    const blocks = await b.build(ctx({ tools: [makeTool('bigtool', long)], tokenSavingMode: true }));
+    const toolsText = (blocks[1] as TextBlock).text;
+    expect(toolsText).toContain('y'.repeat(60));
+    expect(toolsText).not.toContain('y'.repeat(61));
+  });
+
+  it('places cache_control (ephemeral, 5m) at end of stable prefix (layer 2)', async () => {
+    const b = new DefaultSystemPromptBuilder();
+    const blocks = await b.build(ctx());
+    expect((blocks[1] as TextBlock).cache_control).toEqual({ type: 'ephemeral', ttl: '5m' });
+    expect((blocks[0] as TextBlock).cache_control).toBeUndefined();
+  });
+
+  it('env layer includes platform, node, model, cwd', async () => {
+    const b = new DefaultSystemPromptBuilder();
+    const blocks = await b.build(ctx());
+    const env = (blocks[2] as TextBlock).text;
+    expect(env).toContain('platform:');
+    expect(env).toContain('node:');
+    expect(env).toContain('model: anthropic/claude-sonnet-4-6');
+    expect(env).toContain('cwd:');
+  });
+
+  it('returns cached blocks on identical signature (no rebuild)', async () => {
+    const b = new DefaultSystemPromptBuilder();
+    const c = ctx();
+    const first = await b.build(c);
+    const second = await b.build(c);
+    expect(second).toBe(first);
+  });
+
+  it('rebuilds when tool set changes', async () => {
+    const b = new DefaultSystemPromptBuilder();
+    const first = await b.build(ctx({ tools: [makeTool('a')] }));
+    const second = await b.build(ctx({ tools: [makeTool('b')] }));
+    expect(second).not.toBe(first);
+  });
+
+  it('throws PROMPT_BUDGET_EXCEEDED when layers 1+2+3 exceed budget', async () => {
+    const b = new DefaultSystemPromptBuilder();
+    const huge: Tool[] = [];
+    for (let i = 0; i < 500; i++) {
+      huge.push(makeTool(`t${i}`, 'z'.repeat(200)));
+    }
+    await expect(b.build(ctx({ tools: huge }))).rejects.toThrow(/exceed budget/);
+  });
+});