@flowcodex/core 0.3.0

package/tests/errors.test.ts

@@ -0,0 +1,429 @@
+import { describe, it, expect } from 'vitest';
+import {
+  FlowCodexError,
+  ToolError,
+  ConfigError,
+  PluginError,
+  AgentError,
+  PermissionError,
+  SessionError,
+  FsError,
+  toFlowCodexError,
+  isFlowCodexError,
+  isToolError,
+  isConfigError,
+  isPluginError,
+  isSessionError,
+  isAgentError,
+  isPermissionError,
+  isFsError,
+  ERROR_CODES,
+} from '../src/types/errors.js';
+import { toErrorMessage } from '../src/utils/error.js';
+
+describe('toErrorMessage', () => {
+  it('extracts message from Error', () => {
+    expect(toErrorMessage(new Error('test msg'))).toBe('test msg');
+  });
+
+  it('stringifies non-Error values', () => {
+    expect(toErrorMessage('plain string')).toBe('plain string');
+    expect(toErrorMessage(42)).toBe('42');
+    expect(toErrorMessage(null)).toBe('null');
+    expect(toErrorMessage(undefined)).toBe('undefined');
+  });
+});
+
+describe('FlowCodexError', () => {
+  it('creates with all fields', () => {
+    const err = new FlowCodexError({
+      message: 'something broke',
+      code: ERROR_CODES.UNKNOWN,
+      subsystem: 'general',
+      severity: 'error',
+      recoverable: true,
+      context: { key: 'value' },
+    });
+    expect(err.message).toBe('something broke');
+    expect(err.code).toBe('UNKNOWN');
+    expect(err.subsystem).toBe('general');
+    expect(err.severity).toBe('error');
+    expect(err.recoverable).toBe(true);
+    expect(err.context).toEqual({ key: 'value' });
+    expect(err.name).toBe('FlowCodexError');
+    expect(err instanceof Error).toBe(true);
+  });
+
+  it('defaults severity to error', () => {
+    const err = new FlowCodexError({
+      message: 'x',
+      code: ERROR_CODES.UNKNOWN,
+      subsystem: 'general',
+    });
+    expect(err.severity).toBe('error');
+    expect(err.recoverable).toBe(false);
+    expect(err.context).toBeUndefined();
+  });
+
+  it('describe() includes code, message, and context', () => {
+    const err = new FlowCodexError({
+      message: 'failed',
+      code: ERROR_CODES.PROVIDER_NETWORK_ERROR,
+      subsystem: 'provider',
+      context: { url: 'https://example.com', retry: 3 },
+    });
+    const d = err.describe();
+    expect(d).toContain('PROVIDER_NETWORK_ERROR');
+    expect(d).toContain('failed');
+    expect(d).toContain('url=https://example.com');
+    expect(d).toContain('retry=3');
+  });
+
+  it('describe() with no context omits brackets', () => {
+    const err = new FlowCodexError({
+      message: 'plain',
+      code: ERROR_CODES.UNKNOWN,
+      subsystem: 'general',
+    });
+    expect(err.describe()).toBe('UNKNOWN: plain');
+  });
+
+  it('preserves cause', () => {
+    const cause = new Error('root cause');
+    const err = new FlowCodexError({
+      message: 'wrapper',
+      code: ERROR_CODES.AGENT_RUN_FAILED,
+      subsystem: 'agent',
+      cause,
+    });
+    expect(err.cause).toBe(cause);
+  });
+});
+
+describe('ToolError', () => {
+  it('sets subsystem to tool and includes toolName in context', () => {
+    const err = new ToolError({
+      message: 'not found',
+      code: ERROR_CODES.TOOL_NOT_FOUND,
+      toolName: 'bash',
+    });
+    expect(err.subsystem).toBe('tool');
+    expect(err.toolName).toBe('bash');
+    expect(err.context).toEqual({ tool: 'bash' });
+    expect(err.name).toBe('ToolError');
+    expect(isFlowCodexError(err)).toBe(true);
+  });
+
+  it('merges extra context with tool name', () => {
+    const err = new ToolError({
+      message: 'timeout',
+      code: ERROR_CODES.TOOL_TIMEOUT,
+      toolName: 'read',
+      context: { duration: 5000 },
+    });
+    expect(err.context).toEqual({ tool: 'read', duration: 5000 });
+  });
+});
+
+describe('ConfigError', () => {
+  it('is always fatal and non-recoverable', () => {
+    const err = new ConfigError({
+      message: 'bad config',
+      code: ERROR_CODES.CONFIG_INVALID,
+    });
+    expect(err.severity).toBe('fatal');
+    expect(err.recoverable).toBe(false);
+    expect(err.subsystem).toBe('config');
+    expect(err.name).toBe('ConfigError');
+  });
+});
+
+describe('PluginError', () => {
+  it('missing dependency is recoverable', () => {
+    const err = new PluginError({
+      message: 'missing dep',
+      code: ERROR_CODES.PLUGIN_MISSING_DEPENDENCY,
+      pluginName: 'my-plugin',
+    });
+    expect(err.recoverable).toBe(true);
+    expect(err.pluginName).toBe('my-plugin');
+  });
+
+  it('load failed is not recoverable', () => {
+    const err = new PluginError({
+      message: 'load fail',
+      code: ERROR_CODES.PLUGIN_LOAD_FAILED,
+      pluginName: 'bad-plugin',
+    });
+    expect(err.recoverable).toBe(false);
+  });
+});
+
+describe('AgentError', () => {
+  it('aborted is warning severity', () => {
+    const err = new AgentError({
+      message: 'user aborted',
+      code: ERROR_CODES.AGENT_ABORTED,
+    });
+    expect(err.severity).toBe('warning');
+  });
+
+  it('iteration limit is recoverable by default', () => {
+    const err = new AgentError({
+      message: 'limit reached',
+      code: ERROR_CODES.AGENT_ITERATION_LIMIT,
+    });
+    expect(err.recoverable).toBe(true);
+  });
+
+  it('budget exceeded is not recoverable by default', () => {
+    const err = new AgentError({
+      message: 'cost cap hit',
+      code: ERROR_CODES.AGENT_BUDGET_EXCEEDED,
+    });
+    expect(err.recoverable).toBe(false);
+    expect(err.severity).toBe('error');
+  });
+
+  it('accepts COMPACTION_FAILED', () => {
+    const err = new AgentError({
+      message: 'could not reduce context below hard threshold',
+      code: ERROR_CODES.COMPACTION_FAILED,
+    });
+    expect(err.code).toBe('COMPACTION_FAILED');
+    expect(err.subsystem).toBe('agent');
+  });
+
+  it('accepts PROMPT_BUDGET_EXCEEDED', () => {
+    const err = new AgentError({
+      message: 'system prompt layers exceeded budget',
+      code: ERROR_CODES.PROMPT_BUDGET_EXCEEDED,
+    });
+    expect(err.code).toBe('PROMPT_BUDGET_EXCEEDED');
+    expect(err.subsystem).toBe('agent');
+  });
+});
+
+describe('PermissionError', () => {
+  it('reuses TOOL_PERMISSION_DENIED code with tool subsystem', () => {
+    const err = new PermissionError({
+      message: 'denied by policy',
+      tool: 'bash',
+      pattern: 'rm -rf *',
+      source: 'trust',
+    });
+    expect(err.code).toBe('TOOL_PERMISSION_DENIED');
+    expect(err.subsystem).toBe('tool');
+    expect(err.name).toBe('PermissionError');
+    expect(err.recoverable).toBe(false);
+    expect(err.tool).toBe('bash');
+    expect(err.pattern).toBe('rm -rf *');
+    expect(err.source).toBe('trust');
+  });
+
+  it('carries tool, pattern, and source in context', () => {
+    const err = new PermissionError({
+      message: 'user denied',
+      tool: 'edit',
+      source: 'user',
+    });
+    expect(err.context).toEqual({ tool: 'edit', pattern: undefined, source: 'user' });
+  });
+
+  it('is a FlowCodexError but not a ToolError', () => {
+    const err = new PermissionError({
+      message: 'x',
+      tool: 'bash',
+      source: 'deny',
+    });
+    expect(isFlowCodexError(err)).toBe(true);
+    expect(isPermissionError(err)).toBe(true);
+    expect(isToolError(err)).toBe(false);
+  });
+
+  it('isPermissionError rejects plain errors', () => {
+    expect(isPermissionError(new Error('plain'))).toBe(false);
+  });
+});
+
+describe('SessionError', () => {
+  it('corrupted is not recoverable', () => {
+    const err = new SessionError({
+      message: 'jsonl malformed',
+      code: ERROR_CODES.SESSION_CORRUPTED,
+      sessionId: '01ABC',
+    });
+    expect(err.recoverable).toBe(false);
+    expect(err.sessionId).toBe('01ABC');
+    expect(err.context).toEqual({ sessionId: '01ABC' });
+  });
+
+  it('write failed is warning severity', () => {
+    const err = new SessionError({
+      message: 'disk full',
+      code: ERROR_CODES.SESSION_WRITE_FAILED,
+    });
+    expect(err.severity).toBe('error');
+  });
+});
+
+describe('FsError', () => {
+  it('read failed is not recoverable', () => {
+    const err = new FsError({
+      message: 'no such file',
+      code: ERROR_CODES.FS_READ_FAILED,
+      path: '/missing.txt',
+    });
+    expect(err.recoverable).toBe(false);
+    expect(err.path).toBe('/missing.txt');
+  });
+
+  it('path escape sets path in context', () => {
+    const err = new FsError({
+      message: 'outside project root',
+      code: ERROR_CODES.FS_PATH_ESCAPE,
+      path: '/etc/passwd',
+    });
+    expect(err.code).toBe('FS_PATH_ESCAPE');
+    expect(err.context).toEqual({ path: '/etc/passwd' });
+  });
+});
+
+describe('toFlowCodexError', () => {
+  it('passes through FlowCodexError unchanged', () => {
+    const original = new ToolError({
+      message: 'orig',
+      code: ERROR_CODES.TOOL_NOT_FOUND,
+      toolName: 'x',
+    });
+    const wrapped = toFlowCodexError(original);
+    expect(wrapped).toBe(original);
+  });
+
+  it('wraps plain Error into AgentError', () => {
+    const wrapped = toFlowCodexError(new Error('boom'));
+    expect(wrapped).toBeInstanceOf(AgentError);
+    expect(wrapped.code).toBe('AGENT_RUN_FAILED');
+    expect(wrapped.message).toBe('boom');
+    expect(wrapped.cause).toBeInstanceOf(Error);
+  });
+
+  it('wraps non-Error values', () => {
+    const wrapped = toFlowCodexError('string error');
+    expect(wrapped).toBeInstanceOf(AgentError);
+    expect(wrapped.message).toBe('string error');
+  });
+
+  it('respects custom code', () => {
+    const wrapped = toFlowCodexError(new Error('abort'), ERROR_CODES.AGENT_ABORTED);
+    expect(wrapped.code).toBe('AGENT_ABORTED');
+  });
+});
+
+describe('type guards', () => {
+  it('isFlowCodexError', () => {
+    expect(isFlowCodexError(new FlowCodexError({ message: 'x', code: ERROR_CODES.UNKNOWN, subsystem: 'general' }))).toBe(true);
+    expect(isFlowCodexError(new Error('plain'))).toBe(false);
+  });
+
+  it('isToolError', () => {
+    expect(isToolError(new ToolError({ message: 'x', code: ERROR_CODES.TOOL_TIMEOUT, toolName: 't' }))).toBe(true);
+    expect(isToolError(new Error('plain'))).toBe(false);
+  });
+
+  it('isConfigError', () => {
+    expect(isConfigError(new ConfigError({ message: 'x', code: ERROR_CODES.CONFIG_INVALID }))).toBe(true);
+  });
+
+  it('isPluginError', () => {
+    expect(isPluginError(new PluginError({ message: 'x', code: ERROR_CODES.PLUGIN_LOAD_FAILED, pluginName: 'p' }))).toBe(true);
+  });
+
+  it('isSessionError', () => {
+    expect(isSessionError(new SessionError({ message: 'x', code: ERROR_CODES.SESSION_NOT_FOUND }))).toBe(true);
+  });
+
+  it('isAgentError', () => {
+    expect(isAgentError(new AgentError({ message: 'x', code: ERROR_CODES.AGENT_RUN_FAILED }))).toBe(true);
+  });
+
+  it('isPermissionError', () => {
+    expect(isPermissionError(new PermissionError({ message: 'x', tool: 'bash', source: 'deny' }))).toBe(true);
+    expect(isPermissionError(new Error('plain'))).toBe(false);
+  });
+
+  it('isFsError', () => {
+    expect(isFsError(new FsError({ message: 'x', code: ERROR_CODES.FS_READ_FAILED }))).toBe(true);
+  });
+
+  it('subclasses pass isFlowCodexError', () => {
+    expect(isFlowCodexError(new ToolError({ message: 'x', code: ERROR_CODES.TOOL_TIMEOUT, toolName: 't' }))).toBe(true);
+    expect(isFlowCodexError(new ConfigError({ message: 'x', code: ERROR_CODES.CONFIG_INVALID }))).toBe(true);
+  });
+});
+
+describe('PROVIDER_UNSUPPORTED error code', () => {
+  it('PROVIDER_UNSUPPORTED error code exists', () => {
+    expect(ERROR_CODES.PROVIDER_UNSUPPORTED).toBe('PROVIDER_UNSUPPORTED');
+  });
+
+  it('PROVIDER_NOT_WIRED error code exists', () => {
+    expect(ERROR_CODES.PROVIDER_NOT_WIRED).toBe('PROVIDER_NOT_WIRED');
+  });
+
+  it('FlowCodexError with PROVIDER_UNSUPPORTED has provider subsystem', () => {
+    const err = new FlowCodexError({
+      message: 'unsupported',
+      code: ERROR_CODES.PROVIDER_UNSUPPORTED,
+      subsystem: 'provider',
+    });
+    expect(err.subsystem).toBe('provider');
+    expect(err.recoverable).toBe(false);
+  });
+});
+
+describe('v0.2.1 error codes', () => {
+  it('SSRF_BLOCKED exists', () => {
+    expect(ERROR_CODES.SSRF_BLOCKED).toBe('SSRF_BLOCKED');
+  });
+  it('WEBFETCH_FAILED exists', () => {
+    expect(ERROR_CODES.WEBFETCH_FAILED).toBe('WEBFETCH_FAILED');
+  });
+  it('WEBSEARCH_FAILED exists', () => {
+    expect(ERROR_CODES.WEBSEARCH_FAILED).toBe('WEBSEARCH_FAILED');
+  });
+  it('DIFF_FILE_NOT_FOUND exists', () => {
+    expect(ERROR_CODES.DIFF_FILE_NOT_FOUND).toBe('DIFF_FILE_NOT_FOUND');
+  });
+  it('PATCH_HUNK_FAILED exists', () => {
+    expect(ERROR_CODES.PATCH_HUNK_FAILED).toBe('PATCH_HUNK_FAILED');
+  });
+  it('DEV_TOOL_NOT_FOUND exists', () => {
+    expect(ERROR_CODES.DEV_TOOL_NOT_FOUND).toBe('DEV_TOOL_NOT_FOUND');
+  });
+  it('REPLAY_MISS exists', () => {
+    expect(ERROR_CODES.REPLAY_MISS).toBe('REPLAY_MISS');
+  });
+  it('SESSION_EXPORT_FAILED exists', () => {
+    expect(ERROR_CODES.SESSION_EXPORT_FAILED).toBe('SESSION_EXPORT_FAILED');
+  });
+  it('SESSION_NOT_FOUND already exists', () => {
+    expect(ERROR_CODES.SESSION_NOT_FOUND).toBe('SESSION_NOT_FOUND');
+  });
+  it('FlowCodexError accepts SSRF_BLOCKED', () => {
+    const err = new FlowCodexError({
+      message: 'blocked',
+      code: ERROR_CODES.SSRF_BLOCKED,
+      subsystem: 'general',
+    });
+    expect(err.code).toBe('SSRF_BLOCKED');
+  });
+  it('FlowCodexError accepts REPLAY_MISS', () => {
+    const err = new FlowCodexError({
+      message: 'no recorded response',
+      code: ERROR_CODES.REPLAY_MISS,
+      subsystem: 'provider',
+    });
+    expect(err.code).toBe('REPLAY_MISS');
+  });
+});

package/tests/events-v021.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { EventBus } from '../src/kernel/events.js';
+
+describe('v0.2.1 events', () => {
+  it('emits session.resumed', () => {
+    const bus = new EventBus();
+    let received: { sessionId: string; forkedFrom?: string | undefined } | undefined;
+    bus.on('session.resumed', (p) => {
+      received = p;
+    });
+    bus.emit('session.resumed', { sessionId: 'abc', forkedFrom: 'parent' });
+    expect(received?.sessionId).toBe('abc');
+    expect(received?.forkedFrom).toBe('parent');
+  });
+
+  it('emits session.resumed without forkedFrom', () => {
+    const bus = new EventBus();
+    let received: { sessionId: string; forkedFrom?: string | undefined } | undefined;
+    bus.on('session.resumed', (p) => {
+      received = p;
+    });
+    bus.emit('session.resumed', { sessionId: 'xyz' });
+    expect(received?.sessionId).toBe('xyz');
+    expect(received?.forkedFrom).toBeUndefined();
+  });
+
+  it('emits session.summary_written', () => {
+    const bus = new EventBus();
+    let received: { sessionId: string; summary: unknown } | undefined;
+    bus.on('session.summary_written', (p) => {
+      received = p;
+    });
+    const summary = { id: 's1', title: 'test' };
+    bus.emit('session.summary_written', { sessionId: 's1', summary });
+    expect(received?.sessionId).toBe('s1');
+    expect(received?.summary).toBe(summary);
+  });
+
+  it('emits tool.tier_filtered', () => {
+    const bus = new EventBus();
+    let received: { total: number; kept: number } | undefined;
+    bus.on('tool.tier_filtered', (p) => {
+      received = p;
+    });
+    bus.emit('tool.tier_filtered', { total: 15, kept: 10 });
+    expect(received?.total).toBe(15);
+    expect(received?.kept).toBe(10);
+  });
+
+  it('emits ssrf.blocked', () => {
+    const bus = new EventBus();
+    let received: { url: string; ip: string; reason: string } | undefined;
+    bus.on('ssrf.blocked', (p) => {
+      received = p;
+    });
+    bus.emit('ssrf.blocked', { url: 'http://10.0.0.1', ip: '10.0.0.1', reason: 'private' });
+    expect(received?.url).toBe('http://10.0.0.1');
+    expect(received?.reason).toBe('private');
+  });
+});

package/tests/events-v022.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+import { EventBus } from '../src/kernel/events.js';
+import { ERROR_CODES, FlowCodexError } from '../src/types/errors.js';
+
+describe('v0.2.2 error codes', () => {
+  it('PROVIDER_UNSUPPORTED_MODALITY exists', () => {
+    expect(ERROR_CODES.PROVIDER_UNSUPPORTED_MODALITY).toBe('PROVIDER_UNSUPPORTED_MODALITY');
+  });
+  it('TOOL_BATCH_FAILED exists', () => {
+    expect(ERROR_CODES.TOOL_BATCH_FAILED).toBe('TOOL_BATCH_FAILED');
+  });
+  it('TOOL_BATCH_TOO_LARGE exists', () => {
+    expect(ERROR_CODES.TOOL_BATCH_TOO_LARGE).toBe('TOOL_BATCH_TOO_LARGE');
+  });
+  it('TOOL_NESTED_BATCH exists', () => {
+    expect(ERROR_CODES.TOOL_NESTED_BATCH).toBe('TOOL_NESTED_BATCH');
+  });
+  it('TOOL_INVALID_ATTACHMENT exists', () => {
+    expect(ERROR_CODES.TOOL_INVALID_ATTACHMENT).toBe('TOOL_INVALID_ATTACHMENT');
+  });
+  it('TOOL_UNSUPPORTED_PROVIDER exists', () => {
+    expect(ERROR_CODES.TOOL_UNSUPPORTED_PROVIDER).toBe('TOOL_UNSUPPORTED_PROVIDER');
+  });
+  it('AGENT_STRUCTURED_OUTPUT_NOT_PRODUCED exists', () => {
+    expect(ERROR_CODES.AGENT_STRUCTURED_OUTPUT_NOT_PRODUCED).toBe('AGENT_STRUCTURED_OUTPUT_NOT_PRODUCED');
+  });
+  it('FlowCodexError accepts PROVIDER_UNSUPPORTED_MODALITY', () => {
+    const err = new FlowCodexError({
+      message: 'no vision',
+      code: ERROR_CODES.PROVIDER_UNSUPPORTED_MODALITY,
+      subsystem: 'provider',
+    });
+    expect(err.code).toBe('PROVIDER_UNSUPPORTED_MODALITY');
+    expect(err.subsystem).toBe('provider');
+  });
+  it('FlowCodexError accepts TOOL_NESTED_BATCH', () => {
+    const err = new FlowCodexError({
+      message: 'nested',
+      code: ERROR_CODES.TOOL_NESTED_BATCH,
+      subsystem: 'tool',
+    });
+    expect(err.code).toBe('TOOL_NESTED_BATCH');
+  });
+});
+
+describe('v0.2.2 events', () => {
+  it('emits tool.batch_started', () => {
+    const bus = new EventBus();
+    let captured: unknown = null;
+    bus.on('tool.batch_started', (p) => { captured = p; });
+    bus.emit('tool.batch_started', { count: 3, names: ['read', 'read', 'glob'] });
+    expect(captured).toEqual({ count: 3, names: ['read', 'read', 'glob'] });
+  });
+  it('emits tool.batch_completed', () => {
+    const bus = new EventBus();
+    let captured: unknown = null;
+    bus.on('tool.batch_completed', (p) => { captured = p; });
+    bus.emit('tool.batch_completed', { count: 3, succeeded: 2, failed: 1, durationMs: 42 });
+    expect(captured).toEqual({ count: 3, succeeded: 2, failed: 1, durationMs: 42 });
+  });
+  it('emits provider.structured_output', () => {
+    const bus = new EventBus();
+    let captured: unknown = null;
+    bus.on('provider.structured_output', (p) => { captured = p; });
+    bus.emit('provider.structured_output', { name: 'structured_output', valid: true });
+    expect(captured).toEqual({ name: 'structured_output', valid: true });
+  });
+  it('emits provider.modality_rejected', () => {
+    const bus = new EventBus();
+    let captured: unknown = null;
+    bus.on('provider.modality_rejected', (p) => { captured = p; });
+    bus.emit('provider.modality_rejected', { provider: 'openai', model: 'gpt-4', modality: 'pdf' });
+    expect(captured).toEqual({ provider: 'openai', model: 'gpt-4', modality: 'pdf' });
+  });
+});