@flowcodex/core 0.3.0

package/tests/token-counter.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect } from 'vitest';
+import { DefaultTokenCounter } from '../src/infrastructure/token-counter.js';
+
+describe('DefaultTokenCounter', () => {
+  describe('estimate', () => {
+    it('estimates using 3.5 ratio for Anthropic models', () => {
+      const tc = new DefaultTokenCounter();
+      expect(tc.estimate('hello world', 'claude-sonnet-4-6')).toBe(Math.ceil(11 / 3.5));
+    });
+
+    it('estimates using 4.0 ratio for non-Anthropic models', () => {
+      const tc = new DefaultTokenCounter();
+      expect(tc.estimate('hello world', 'gpt-4o')).toBe(Math.ceil(11 / 4));
+    });
+
+    it('uses default ratio when no model specified', () => {
+      const tc = new DefaultTokenCounter();
+      expect(tc.estimate('hello world')).toBe(Math.ceil(11 / 4));
+    });
+
+    it('returns at least 1 for empty string', () => {
+      const tc = new DefaultTokenCounter();
+      expect(tc.estimate('')).toBe(1);
+    });
+  });
+
+  describe('account + total', () => {
+    it('accumulates input and output tokens', () => {
+      const tc = new DefaultTokenCounter();
+      tc.account({ input: 100, output: 50 });
+      tc.account({ input: 200, output: 75 });
+      expect(tc.total()).toBe(425);
+    });
+
+    it('tracks cache tokens separately', () => {
+      const tc = new DefaultTokenCounter();
+      tc.account({ input: 100, output: 50, cache_read: 80, cache_creation: 20 });
+      expect(tc.total()).toBe(150);
+    });
+  });
+
+  describe('request tokens', () => {
+    it('setRequestTokens + currentRequestTokens', () => {
+      const tc = new DefaultTokenCounter();
+      tc.setRequestTokens(5000);
+      expect(tc.currentRequestTokens()).toBe(5000);
+    });
+  });
+
+  describe('estimateCost', () => {
+    it('returns 0 when pricing not set', () => {
+      const tc = new DefaultTokenCounter();
+      expect(tc.estimateCost('claude-sonnet-4-6', { input: 1000, output: 500 })).toBe(0);
+    });
+
+    it('calculates cost from pricing', () => {
+      const tc = new DefaultTokenCounter();
+      tc.setPricing('claude-sonnet-4-6', {
+        input: 3,
+        output: 15,
+        cacheRead: 0.3,
+        cacheWrite: 3.75,
+      });
+      const cost = tc.estimateCost('claude-sonnet-4-6', {
+        input: 1_000_000,
+        output: 1_000_000,
+        cache_read: 1_000_000,
+        cache_creation: 1_000_000,
+      });
+      expect(cost).toBeCloseTo(3 + 15 + 0.3 + 3.75, 2);
+    });
+
+    it('handles missing cache fields', () => {
+      const tc = new DefaultTokenCounter();
+      tc.setPricing('test-model', {
+        input: 1,
+        output: 2,
+        cacheRead: 0.1,
+        cacheWrite: 1.25,
+      });
+      const cost = tc.estimateCost('test-model', { input: 1_000_000, output: 1_000_000 });
+      expect(cost).toBeCloseTo(3, 2);
+    });
+  });
+
+  describe('calibration', () => {
+    it('starts with anthropic ratio for claude models', () => {
+      const tc = new DefaultTokenCounter();
+      tc.calibrate('claude-sonnet-4-6');
+      expect(tc.estimate('hello', 'claude-sonnet-4-6')).toBe(Math.ceil(5 / 3.5));
+    });
+
+    it('starts with default ratio for non-claude', () => {
+      const tc = new DefaultTokenCounter();
+      tc.calibrate('gpt-4o');
+      expect(tc.estimate('hello', 'gpt-4o')).toBe(Math.ceil(5 / 4));
+    });
+  });
+
+  describe('estimateRequestTokens', () => {
+    it('returns at least 1 for empty system and messages', () => {
+      const tc = new DefaultTokenCounter();
+      expect(tc.estimateRequestTokens([], [])).toBe(1);
+    });
+
+    it('counts system text blocks', () => {
+      const tc = new DefaultTokenCounter();
+      const tokens = tc.estimateRequestTokens(
+        [{ type: 'text', text: 'hello world' }],
+        [],
+        undefined,
+        'claude-sonnet-4-6',
+      );
+      expect(tokens).toBe(Math.ceil(11 / 3.5));
+    });
+
+    it('counts message text, tool_use input, and tool_result content', () => {
+      const tc = new DefaultTokenCounter();
+      const tokens = tc.estimateRequestTokens(
+        [],
+        [
+          { role: 'user', content: 'abc' },
+          {
+            role: 'assistant',
+            content: [
+              { type: 'text', text: 'de' },
+              { type: 'tool_use', id: '1', name: 'read', input: { path: '/x' } },
+            ],
+          },
+          {
+            role: 'user',
+            content: [{ type: 'tool_result', tool_use_id: '1', content: 'result text' }],
+          },
+        ],
+        undefined,
+        'claude-sonnet-4-6',
+      );
+      // 'abc'(3) + 'de'(2) + JSON({path:'/x'}) + 'result text'(11)
+      const toolUseJson = JSON.stringify({ path: '/x' }).length;
+      const chars = 3 + 2 + toolUseJson + 11;
+      expect(tokens).toBe(Math.ceil(chars / 3.5));
+    });
+
+    it('counts tool schemas when provided (raises estimate vs no tools)', () => {
+      const tc = new DefaultTokenCounter();
+      const system = [{ type: 'text', text: 'sys' }] as const;
+      const without = tc.estimateRequestTokens(system, [], undefined, 'claude-sonnet-4-6');
+      const withTools = tc.estimateRequestTokens(
+        system,
+        [],
+        [{ name: 'read', description: 'desc', inputSchema: { type: 'object', properties: { path: { type: 'string' } } } }],
+        'claude-sonnet-4-6',
+      );
+      expect(withTools).toBeGreaterThan(without);
+    });
+
+    it('uses default ratio when model omitted', () => {
+      const tc = new DefaultTokenCounter();
+      const tokens = tc.estimateRequestTokens([{ type: 'text', text: 'hello world' }], []);
+      expect(tokens).toBe(Math.ceil(11 / 4));
+    });
+  });
+});

package/tests/tokens.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import { TOKENS } from '../src/kernel/tokens.js';
+import { Container } from '../src/kernel/container.js';
+
+describe('TOKENS', () => {
+  it('exports exactly 15 tokens', () => {
+    const keys = Object.keys(TOKENS);
+    expect(keys).toHaveLength(15);
+  });
+
+  it('each token is a unique symbol', () => {
+    const symbols = Object.values(TOKENS);
+    const set = new Set(symbols);
+    expect(set.size).toBe(15);
+  });
+
+  it('all expected tokens are present', () => {
+    expect(TOKENS).toHaveProperty('Logger');
+    expect(TOKENS).toHaveProperty('TokenCounter');
+    expect(TOKENS).toHaveProperty('SessionStore');
+    expect(TOKENS).toHaveProperty('ConfigStore');
+    expect(TOKENS).toHaveProperty('ConfigLoader');
+    expect(TOKENS).toHaveProperty('PermissionPolicy');
+    expect(TOKENS).toHaveProperty('Compactor');
+    expect(TOKENS).toHaveProperty('PathResolver');
+    expect(TOKENS).toHaveProperty('Renderer');
+    expect(TOKENS).toHaveProperty('InputReader');
+    expect(TOKENS).toHaveProperty('ErrorHandler');
+    expect(TOKENS).toHaveProperty('RetryPolicy');
+    expect(TOKENS).toHaveProperty('SystemPromptBuilder');
+    expect(TOKENS).toHaveProperty('SecretScrubber');
+    expect(TOKENS).toHaveProperty('ProviderRunner');
+  });
+
+  it('tokens work with Container', () => {
+    const c = new Container();
+    c.bind(TOKENS.Logger, () => ({ log: () => {} }));
+    expect(c.has(TOKENS.Logger)).toBe(true);
+    const logger = c.resolve(TOKENS.Logger);
+    expect(logger).toEqual({ log: expect.any(Function) });
+  });
+});

package/tests/tool-executor.test.ts

@@ -0,0 +1,452 @@
+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 { ToolExecutor } from '../src/execution/tool-executor.js';
+import { ToolRegistry } from '../src/execution/tool-registry.js';
+import { AgentContext } from '../src/agent/context.js';
+import type { Tool } from '../src/types/tool.js';
+
+let tmpDir: string;
+
+async function setupTmp(): Promise<string> {
+  tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'fcx-exec-'));
+  return tmpDir;
+}
+
+async function cleanupTmp(): Promise<void> {
+  await fsp.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+}
+
+function makeCtx(dir: string): AgentContext {
+  return new AgentContext({
+    model: { provider: 'test', model: 'test-model' },
+    projectRoot: dir,
+    cwd: dir,
+  });
+}
+
+function makeTool(
+  name: string,
+  executeFn: (input: unknown, ctx: unknown, opts: { signal: AbortSignal }) => Promise<unknown>,
+  opts: Partial<Tool> = {},
+): Tool {
+  return {
+    name,
+    description: `test ${name}`,
+    inputSchema: { type: 'object', properties: {}, required: [] },
+    permission: 'auto',
+    mutating: false,
+    ...opts,
+    async execute(input, ctx, execOpts) {
+      return executeFn(input, ctx, execOpts);
+    },
+  };
+}
+
+describe('ToolExecutor', () => {
+  beforeEach(async () => {
+    await setupTmp();
+  });
+  afterEach(async () => {
+    await cleanupTmp();
+  });
+
+  it('executes a single tool and returns result', async () => {
+    const reg = new ToolRegistry();
+    reg.register(
+      makeTool('echo', async (input) => ({ echo: (input as { msg: string }).msg })),
+      'test',
+    );
+    const exec = new ToolExecutor(reg);
+    const ctx = makeCtx(tmpDir);
+
+    const { results } = await exec.executeBatch(
+      [{ id: 't1', name: 'echo', input: { msg: 'hello' } }],
+      ctx,
+    );
+
+    expect(results).toHaveLength(1);
+    expect(results[0]!.block.type).toBe('tool_result');
+    expect(results[0]!.block.is_error).toBeFalsy();
+    expect(results[0]!.block.content).toContain('hello');
+  });
+
+  it('returns error result for unknown tool', async () => {
+    const reg = new ToolRegistry();
+    const exec = new ToolExecutor(reg);
+    const ctx = makeCtx(tmpDir);
+
+    const { results } = await exec.executeBatch(
+      [{ id: 't1', name: 'missing', input: {} }],
+      ctx,
+    );
+
+    expect(results[0]!.block.is_error).toBe(true);
+    const content = results[0]!.block.content;
+    expect(typeof content === 'string' ? content : '').toContain('not registered');
+  });
+
+  it('returns error result for schema validation failure', async () => {
+    const reg = new ToolRegistry();
+    reg.register(
+      {
+        name: 'greet',
+        description: 'greets',
+        inputSchema: {
+          type: 'object',
+          properties: { name: { type: 'string' } },
+          required: ['name'],
+        },
+        permission: 'auto',
+        mutating: false,
+        async execute(input) {
+          return `Hello ${(input as { name: string }).name}`;
+        },
+      },
+      'test',
+    );
+    const exec = new ToolExecutor(reg);
+    const ctx = makeCtx(tmpDir);
+
+    const { results } = await exec.executeBatch(
+      [{ id: 't1', name: 'greet', input: {} }],
+      ctx,
+    );
+
+    expect(results[0]!.block.is_error).toBe(true);
+    const content = results[0]!.block.content;
+    expect(typeof content === 'string' ? content : '').toContain('Validation errors');
+    expect(typeof content === 'string' ? content : '').toContain('name');
+  });
+
+  it('returns error result when tool throws', async () => {
+    const reg = new ToolRegistry();
+    reg.register(
+      makeTool('boom', async () => {
+        throw new Error('kaboom');
+      }),
+      'test',
+    );
+    const exec = new ToolExecutor(reg);
+    const ctx = makeCtx(tmpDir);
+
+    const { results } = await exec.executeBatch(
+      [{ id: 't1', name: 'boom', input: {} }],
+      ctx,
+    );
+
+    expect(results[0]!.block.is_error).toBe(true);
+    const content = results[0]!.block.content;
+    expect(typeof content === 'string' ? content : '').toContain('kaboom');
+  });
+
+  it('runs read-only tools in parallel (smart strategy)', async () => {
+    const reg = new ToolRegistry();
+    const order: string[] = [];
+    reg.register(
+      makeTool(
+        'ro1',
+        async () => {
+          order.push('ro1-start');
+          await new Promise((r) => setTimeout(r, 50));
+          order.push('ro1-end');
+          return 'ok';
+        },
+        { mutating: false },
+      ),
+      'test',
+    );
+    reg.register(
+      makeTool(
+        'ro2',
+        async () => {
+          order.push('ro2-start');
+          await new Promise((r) => setTimeout(r, 50));
+          order.push('ro2-end');
+          return 'ok';
+        },
+        { mutating: false },
+      ),
+      'test',
+    );
+    const exec = new ToolExecutor(reg);
+    const ctx = makeCtx(tmpDir);
+
+    await exec.executeBatch(
+      [
+        { id: 't1', name: 'ro1', input: {} },
+        { id: 't2', name: 'ro2', input: {} },
+      ],
+      ctx,
+      'smart',
+    );
+
+    const starts = order.filter((s) => s.endsWith('-start'));
+    expect(starts).toContain('ro1-start');
+    expect(starts).toContain('ro2-start');
+    expect(starts).toHaveLength(2);
+  });
+
+  it('runs mutating tools sequentially (smart strategy)', async () => {
+    const reg = new ToolRegistry();
+    const order: string[] = [];
+    reg.register(
+      makeTool(
+        'mut1',
+        async () => {
+          order.push('mut1-start');
+          await new Promise((r) => setTimeout(r, 30));
+          order.push('mut1-end');
+          return 'ok';
+        },
+        { mutating: true },
+      ),
+      'test',
+    );
+    reg.register(
+      makeTool(
+        'mut2',
+        async () => {
+          order.push('mut2-start');
+          await new Promise((r) => setTimeout(r, 30));
+          order.push('mut2-end');
+          return 'ok';
+        },
+        { mutating: true },
+      ),
+      'test',
+    );
+    const exec = new ToolExecutor(reg);
+    const ctx = makeCtx(tmpDir);
+
+    await exec.executeBatch(
+      [
+        { id: 't1', name: 'mut1', input: {} },
+        { id: 't2', name: 'mut2', input: {} },
+      ],
+      ctx,
+      'smart',
+    );
+
+    expect(order).toEqual([
+      'mut1-start',
+      'mut1-end',
+      'mut2-start',
+      'mut2-end',
+    ]);
+  });
+
+  it('preserves original order in results', async () => {
+    const reg = new ToolRegistry();
+    reg.register(makeTool('a', async () => 'A', { mutating: false }), 'test');
+    reg.register(makeTool('b', async () => 'B', { mutating: true }), 'test');
+    reg.register(makeTool('c', async () => 'C', { mutating: false }), 'test');
+    const exec = new ToolExecutor(reg);
+    const ctx = makeCtx(tmpDir);
+
+    const { results } = await exec.executeBatch(
+      [
+        { id: 't1', name: 'a', input: {} },
+        { id: 't2', name: 'b', input: {} },
+        { id: 't3', name: 'c', input: {} },
+      ],
+      ctx,
+      'smart',
+    );
+
+    expect(results.map((r) => r.toolUseId)).toEqual(['t1', 't2', 't3']);
+    expect(results.map((r) => r.block.content)).toEqual(['A', 'B', 'C']);
+  });
+
+  it('does not short-circuit on failure', async () => {
+    const reg = new ToolRegistry();
+    reg.register(
+      makeTool('fail', async () => {
+        throw new Error('oops');
+      }),
+      'test',
+    );
+    reg.register(makeTool('ok', async () => 'still runs'), 'test');
+    const exec = new ToolExecutor(reg);
+    const ctx = makeCtx(tmpDir);
+
+    const { results } = await exec.executeBatch(
+      [
+        { id: 't1', name: 'fail', input: {} },
+        { id: 't2', name: 'ok', input: {} },
+      ],
+      ctx,
+    );
+
+    expect(results).toHaveLength(2);
+    expect(results[0]!.block.is_error).toBe(true);
+    expect(results[1]!.block.is_error).toBeFalsy();
+    expect(results[1]!.block.content).toBe('still runs');
+  });
+
+  it('respects output budget cap', async () => {
+    const reg = new ToolRegistry();
+    reg.register(
+      makeTool('big', async () => 'X'.repeat(2000)),
+      'test',
+    );
+    const exec = new ToolExecutor(reg, { perIterationOutputCapBytes: 500 });
+    const ctx = makeCtx(tmpDir);
+
+    const { results, remainingBudget } = await exec.executeBatch(
+      [{ id: 't1', name: 'big', input: {} }],
+      ctx,
+    );
+
+    expect(remainingBudget).toBe(0);
+    const content = results[0]!.block.content;
+    expect(typeof content === 'string' ? content.length : 0).toBeLessThan(2000);
+    expect(typeof content === 'string' ? content : '').toContain('[truncated');
+  });
+
+  it('aborts tool on parent signal', async () => {
+    const reg = new ToolRegistry();
+    const controller = new AbortController();
+    reg.register(
+      makeTool(
+        'slow',
+        async (_, _ctx, opts) => {
+          for (let i = 0; i < 100; i++) {
+            if (opts.signal.aborted) throw new Error('aborted');
+            await new Promise((r) => setTimeout(r, 20));
+          }
+          return 'done';
+        },
+      ),
+      'test',
+    );
+    const exec = new ToolExecutor(reg);
+    const ctx = new AgentContext({
+      model: { provider: 'test', model: 'test-model' },
+      projectRoot: tmpDir,
+      signal: controller.signal,
+    });
+
+    setTimeout(() => controller.abort(), 30);
+
+    const { results } = await exec.executeBatch(
+      [{ id: 't1', name: 'slow', input: {} }],
+      ctx,
+    );
+
+    expect(results[0]!.block.is_error).toBe(true);
+    const content = results[0]!.block.content;
+    expect(typeof content === 'string' ? content : '').toContain('aborted');
+  });
+
+  it('sequential strategy runs all in order', async () => {
+    const reg = new ToolRegistry();
+    const order: string[] = [];
+    reg.register(
+      makeTool(
+        'a',
+        async () => {
+          order.push('a');
+          return 'A';
+        },
+        { mutating: false },
+      ),
+      'test',
+    );
+    reg.register(
+      makeTool(
+        'b',
+        async () => {
+          order.push('b');
+          return 'B';
+        },
+        { mutating: false },
+      ),
+      'test',
+    );
+    const exec = new ToolExecutor(reg);
+    const ctx = makeCtx(tmpDir);
+
+    await exec.executeBatch(
+      [
+        { id: 't1', name: 'a', input: {} },
+        { id: 't2', name: 'b', input: {} },
+      ],
+      ctx,
+      'sequential',
+    );
+
+    expect(order).toEqual(['a', 'b']);
+  });
+
+  it('parallel strategy runs all concurrently', async () => {
+    const reg = new ToolRegistry();
+    reg.register(
+      makeTool(
+        'mut',
+        async () => {
+          await new Promise((r) => setTimeout(r, 30));
+          return 'ok';
+        },
+        { mutating: true },
+      ),
+      'test',
+    );
+    const exec = new ToolExecutor(reg);
+    const ctx = makeCtx(tmpDir);
+
+    const start = Date.now();
+    await exec.executeBatch(
+      [
+        { id: 't1', name: 'mut', input: {} },
+        { id: 't2', name: 'mut', input: {} },
+      ],
+      ctx,
+      'parallel',
+    );
+    const elapsed = Date.now() - start;
+
+    expect(elapsed).toBeLessThan(55);
+  });
+
+  it('scrubs secrets from tool output', async () => {
+    const reg = new ToolRegistry();
+    reg.register(
+      makeTool('leak', async () => 'key=sk-ant-api03-1234567890abcdef'),
+      'test',
+    );
+    const exec = new ToolExecutor(reg);
+    const ctx = makeCtx(tmpDir);
+
+    const { results } = await exec.executeBatch(
+      [{ id: 't1', name: 'leak', input: {} }],
+      ctx,
+    );
+
+    const content = results[0]!.block.content;
+    expect(typeof content === 'string' ? content : '').not.toContain('sk-ant-api03-1234567890abcdef');
+    expect(typeof content === 'string' ? content : '').toContain('[REDACTED');
+  });
+
+  it('scrubs secrets from error messages', async () => {
+    const reg = new ToolRegistry();
+    reg.register(
+      makeTool('boom', async () => {
+        throw new Error('token=sk-ant-api03-' + 'a'.repeat(95));
+      }),
+      'test',
+    );
+    const exec = new ToolExecutor(reg);
+    const ctx = makeCtx(tmpDir);
+
+    const { results } = await exec.executeBatch(
+      [{ id: 't1', name: 'boom', input: {} }],
+      ctx,
+    );
+
+    const content = results[0]!.block.content;
+    expect(typeof content === 'string' ? content : '').not.toContain('sk-ant-api03-' + 'a'.repeat(95));
+    expect(typeof content === 'string' ? content : '').toContain('[REDACTED');
+  });
+});