@illuma-ai/agents 1.4.0-alpha.6 → 1.5.0

package/src/hooks/__tests__/integration.test.ts

@@ -0,0 +1,337 @@
+// src/hooks/__tests__/integration.test.ts
+import { HumanMessage } from '@langchain/core/messages';
+import { HookRegistry } from '../HookRegistry';
+import { Run } from '@/run';
+import type * as t from '@/types';
+import type {
+  HookCallback,
+  RunStartHookInput,
+  RunStartHookOutput,
+  UserPromptSubmitHookOutput,
+  StopHookInput,
+  StopHookOutput,
+  StopFailureHookOutput,
+} from '../types';
+import { Providers } from '@/common';
+
+const llmConfig: t.LLMConfig = {
+  provider: Providers.OPENAI,
+  streaming: true,
+  streamUsage: false,
+};
+
+const callerConfig = {
+  configurable: { thread_id: 'test-thread' },
+  streamMode: 'values' as const,
+  version: 'v2' as const,
+};
+
+function createRun(
+  hooks: HookRegistry,
+  runId = 'test-run'
+): Promise<Run<t.IState>> {
+  return Run.create<t.IState>({
+    runId,
+    graphConfig: { type: 'standard', llmConfig },
+    returnContent: true,
+    skipCleanup: true,
+    hooks,
+  });
+}
+
+describe('Run-level hook integration', () => {
+  jest.setTimeout(15000);
+
+  describe('RunStart', () => {
+    it('fires with runId, threadId, and messages before the stream', async () => {
+      const registry = new HookRegistry();
+      let captured: RunStartHookInput | undefined;
+      const hook: HookCallback<'RunStart'> = async (
+        input
+      ): Promise<RunStartHookOutput> => {
+        captured = input;
+        return {};
+      };
+      registry.register('RunStart', { hooks: [hook] });
+
+      const run = await createRun(registry);
+      run.Graph!.overrideTestModel(['hello']);
+      const inputs = { messages: [new HumanMessage('hi')] };
+      await run.processStream(inputs, callerConfig);
+
+      expect(captured).toBeDefined();
+      expect(captured!.hook_event_name).toBe('RunStart');
+      expect(captured!.runId).toBe('test-run');
+      expect(captured!.threadId).toBe('test-thread');
+      expect(captured!.messages).toHaveLength(1);
+    });
+  });
+
+  describe('UserPromptSubmit', () => {
+    it('extracts prompt text from the last human message', async () => {
+      const registry = new HookRegistry();
+      let capturedPrompt = '';
+      const hook: HookCallback<'UserPromptSubmit'> = async (
+        input
+      ): Promise<UserPromptSubmitHookOutput> => {
+        capturedPrompt = input.prompt;
+        return {};
+      };
+      registry.register('UserPromptSubmit', { hooks: [hook] });
+
+      const run = await createRun(registry);
+      run.Graph!.overrideTestModel(['response']);
+      const inputs = { messages: [new HumanMessage('hello world')] };
+      await run.processStream(inputs, callerConfig);
+
+      expect(capturedPrompt).toBe('hello world');
+    });
+
+    it('extracts prompt from multi-part content (text + non-text blocks)', async () => {
+      const registry = new HookRegistry();
+      let capturedPrompt = '';
+      const hook: HookCallback<'UserPromptSubmit'> = async (
+        input
+      ): Promise<UserPromptSubmitHookOutput> => {
+        capturedPrompt = input.prompt;
+        return {};
+      };
+      registry.register('UserPromptSubmit', { hooks: [hook] });
+
+      const run = await createRun(registry);
+      run.Graph!.overrideTestModel(['ok']);
+      const msg = new HumanMessage({
+        content: [
+          { type: 'text', text: 'hello' },
+          {
+            type: 'image_url',
+            image_url: { url: 'data:image/png;base64,...' },
+          },
+          { type: 'text', text: 'world' },
+        ],
+      });
+      await run.processStream({ messages: [msg] }, callerConfig);
+
+      expect(capturedPrompt).toBe('hello\nworld');
+    });
+
+    it('yields empty prompt for image-only content', async () => {
+      const registry = new HookRegistry();
+      let capturedPrompt: string | undefined;
+      const hook: HookCallback<'UserPromptSubmit'> = async (
+        input
+      ): Promise<UserPromptSubmitHookOutput> => {
+        capturedPrompt = input.prompt;
+        return {};
+      };
+      registry.register('UserPromptSubmit', { hooks: [hook] });
+
+      const run = await createRun(registry);
+      run.Graph!.overrideTestModel(['ok']);
+      const msg = new HumanMessage({
+        content: [
+          {
+            type: 'image_url',
+            image_url: { url: 'data:image/png;base64,...' },
+          },
+        ],
+      });
+      await run.processStream({ messages: [msg] }, callerConfig);
+
+      expect(capturedPrompt).toBe('');
+    });
+
+    it('fires with empty prompt when human message has no text blocks', async () => {
+      const registry = new HookRegistry();
+      let capturedPrompt: string | undefined;
+      const hook: HookCallback<'UserPromptSubmit'> = async (
+        input
+      ): Promise<UserPromptSubmitHookOutput> => {
+        capturedPrompt = input.prompt;
+        return {};
+      };
+      registry.register('UserPromptSubmit', { hooks: [hook] });
+
+      const run = await createRun(registry);
+      run.Graph!.overrideTestModel(['ok']);
+      const msg = new HumanMessage({ content: [] });
+      await run.processStream({ messages: [msg] }, callerConfig);
+
+      expect(capturedPrompt).toBe('');
+    });
+
+    it('aborts the run when hook returns deny', async () => {
+      const registry = new HookRegistry();
+      let stopFired = false;
+      const denyHook: HookCallback<
+        'UserPromptSubmit'
+      > = async (): Promise<UserPromptSubmitHookOutput> => ({
+        decision: 'deny',
+        reason: 'blocked by policy',
+      });
+      const stopHook: HookCallback<
+        'Stop'
+      > = async (): Promise<StopHookOutput> => {
+        stopFired = true;
+        return {};
+      };
+      registry.register('UserPromptSubmit', { hooks: [denyHook] });
+      registry.register('Stop', { hooks: [stopHook] });
+
+      const run = await createRun(registry);
+      run.Graph!.overrideTestModel(['should not reach']);
+      const inputs = { messages: [new HumanMessage('hi')] };
+      const result = await run.processStream(inputs, callerConfig);
+
+      expect(result).toBeUndefined();
+      expect(stopFired).toBe(false);
+    });
+
+    it('aborts the run when hook returns ask (v1 — no interactive flow)', async () => {
+      const registry = new HookRegistry();
+      const askHook: HookCallback<
+        'UserPromptSubmit'
+      > = async (): Promise<UserPromptSubmitHookOutput> => ({
+        decision: 'ask',
+        reason: 'needs confirmation',
+      });
+      registry.register('UserPromptSubmit', { hooks: [askHook] });
+
+      const run = await createRun(registry);
+      run.Graph!.overrideTestModel(['should not reach']);
+      const inputs = { messages: [new HumanMessage('hi')] };
+      const result = await run.processStream(inputs, callerConfig);
+
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('Stop', () => {
+    it('fires after a successful stream with accumulated messages', async () => {
+      const registry = new HookRegistry();
+      let captured: StopHookInput | undefined;
+      const hook: HookCallback<'Stop'> = async (
+        input
+      ): Promise<StopHookOutput> => {
+        captured = input;
+        return {};
+      };
+      registry.register('Stop', { hooks: [hook] });
+
+      const run = await createRun(registry);
+      run.Graph!.overrideTestModel(['agent reply']);
+      const inputs = { messages: [new HumanMessage('hi')] };
+      await run.processStream(inputs, callerConfig);
+
+      expect(captured).toBeDefined();
+      expect(captured!.hook_event_name).toBe('Stop');
+      expect(captured!.runId).toBe('test-run');
+      expect(captured!.stopHookActive).toBe(false);
+      expect(captured!.messages.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it('does not fire when the stream throws an error', async () => {
+      const registry = new HookRegistry();
+      let stopFired = false;
+      const hook: HookCallback<'Stop'> = async (): Promise<StopHookOutput> => {
+        stopFired = true;
+        return {};
+      };
+      registry.register('Stop', { hooks: [hook] });
+
+      const run = await createRun(registry, 'error-run');
+      run.Graph!.overrideTestModel([]);
+
+      const inputs = { messages: [new HumanMessage('hi')] };
+      try {
+        await run.processStream(inputs, callerConfig);
+      } catch {
+        /* expected */
+      }
+
+      expect(stopFired).toBe(false);
+    });
+  });
+
+  describe('StopFailure', () => {
+    it('fires when the stream throws and preserves the original error', async () => {
+      const registry = new HookRegistry();
+      let capturedError = '';
+      const hook: HookCallback<'StopFailure'> = async (
+        input
+      ): Promise<StopFailureHookOutput> => {
+        capturedError = input.error;
+        return {};
+      };
+      registry.register('StopFailure', { hooks: [hook] });
+
+      const run = await createRun(registry, 'fail-run');
+      run.Graph!.overrideTestModel([]);
+
+      const inputs = { messages: [new HumanMessage('hi')] };
+      let thrownError: Error | undefined;
+      try {
+        await run.processStream(inputs, callerConfig);
+      } catch (err) {
+        thrownError = err instanceof Error ? err : new Error(String(err));
+      }
+
+      expect(thrownError).toBeDefined();
+      expect(typeof capturedError).toBe('string');
+      expect(capturedError.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('session teardown', () => {
+    it('clears session matchers after processStream completes', async () => {
+      const registry = new HookRegistry();
+      registry.registerSession('test-run', 'RunStart', {
+        hooks: [async (): Promise<RunStartHookOutput> => ({})],
+      });
+      expect(registry.getMatchers('RunStart', 'test-run')).toHaveLength(1);
+
+      const run = await createRun(registry);
+      run.Graph!.overrideTestModel(['done']);
+      const inputs = { messages: [new HumanMessage('hi')] };
+      await run.processStream(inputs, callerConfig);
+
+      expect(registry.getMatchers('RunStart', 'test-run')).toHaveLength(0);
+    });
+
+    it('clears session even when the stream errors', async () => {
+      const registry = new HookRegistry();
+      registry.registerSession('error-run', 'RunStart', {
+        hooks: [async (): Promise<RunStartHookOutput> => ({})],
+      });
+
+      const run = await createRun(registry, 'error-run');
+      run.Graph!.overrideTestModel([]);
+
+      const inputs = { messages: [new HumanMessage('hi')] };
+      try {
+        await run.processStream(inputs, callerConfig);
+      } catch {
+        /* expected */
+      }
+
+      expect(registry.getMatchers('RunStart', 'error-run')).toHaveLength(0);
+    });
+  });
+
+  describe('no-hooks baseline', () => {
+    it('works identically when no hooks registry is provided', async () => {
+      const run = await Run.create<t.IState>({
+        runId: 'no-hooks-run',
+        graphConfig: { type: 'standard', llmConfig },
+        returnContent: true,
+        skipCleanup: true,
+      });
+      run.Graph!.overrideTestModel(['response']);
+      const inputs = { messages: [new HumanMessage('hi')] };
+      const result = await run.processStream(inputs, callerConfig);
+
+      expect(result).toBeDefined();
+      expect(result!.length).toBeGreaterThan(0);
+    });
+  });
+});

package/src/hooks/__tests__/matchers.test.ts

@@ -0,0 +1,238 @@
+// src/hooks/__tests__/matchers.test.ts
+import {
+  matchesQuery,
+  clearMatcherCache,
+  getMatcherCacheSize,
+  hasNestedQuantifier,
+  MAX_PATTERN_LENGTH,
+  MAX_CACHE_SIZE,
+} from '../matchers';
+
+describe('matchesQuery', () => {
+  beforeEach(() => {
+    clearMatcherCache();
+  });
+
+  it('treats undefined pattern as a wildcard match', () => {
+    expect(matchesQuery(undefined, 'Bash')).toBe(true);
+    expect(matchesQuery(undefined, '')).toBe(true);
+    expect(matchesQuery(undefined, undefined)).toBe(true);
+  });
+
+  it('treats empty-string pattern as a wildcard match', () => {
+    expect(matchesQuery('', 'Bash')).toBe(true);
+    expect(matchesQuery('', undefined)).toBe(true);
+  });
+
+  it('returns false when the pattern is set but the query is absent', () => {
+    expect(matchesQuery('Bash', undefined)).toBe(false);
+    expect(matchesQuery('Bash', '')).toBe(false);
+  });
+
+  it('runs the pattern as a regex against the query', () => {
+    expect(matchesQuery('Bash', 'Bash')).toBe(true);
+    expect(matchesQuery('^Bash$', 'Bash')).toBe(true);
+    expect(matchesQuery('^Bash$', 'BashExtra')).toBe(false);
+    expect(matchesQuery('Bash|Shell', 'Shell')).toBe(true);
+    expect(matchesQuery('mcp_.*_search', 'mcp_github_search')).toBe(true);
+  });
+
+  it('does not throw on invalid regex and returns false instead', () => {
+    expect(() => matchesQuery('[unclosed', 'anything')).not.toThrow();
+    expect(matchesQuery('[unclosed', 'anything')).toBe(false);
+  });
+
+  describe('pattern length bound', () => {
+    it('rejects patterns longer than MAX_PATTERN_LENGTH', () => {
+      const tooLong = 'a'.repeat(MAX_PATTERN_LENGTH + 1);
+      expect(matchesQuery(tooLong, 'aaa')).toBe(false);
+    });
+
+    it('accepts patterns exactly at MAX_PATTERN_LENGTH', () => {
+      const atLimit = 'a'.repeat(MAX_PATTERN_LENGTH);
+      expect(matchesQuery(atLimit, 'a'.repeat(MAX_PATTERN_LENGTH))).toBe(true);
+    });
+  });
+
+  describe('compilation cache', () => {
+    it('caches successful compiles so the same RegExp object is reused', () => {
+      const spy = jest.spyOn(global, 'RegExp');
+      try {
+        matchesQuery('^Bash$', 'Bash');
+        matchesQuery('^Bash$', 'Edit');
+        matchesQuery('^Bash$', 'Bash');
+        expect(spy).toHaveBeenCalledTimes(1);
+      } finally {
+        spy.mockRestore();
+      }
+    });
+
+    it('caches failed compiles so invalid patterns do not re-enter the compiler', () => {
+      const spy = jest.spyOn(global, 'RegExp');
+      try {
+        matchesQuery('[unclosed', 'any');
+        matchesQuery('[unclosed', 'any');
+        matchesQuery('[unclosed', 'other');
+        expect(spy).toHaveBeenCalledTimes(1);
+      } finally {
+        spy.mockRestore();
+      }
+    });
+
+    it('clearMatcherCache drops cached compiles', () => {
+      matchesQuery('^Bash$', 'Bash');
+      clearMatcherCache();
+      const spy = jest.spyOn(global, 'RegExp');
+      try {
+        matchesQuery('^Bash$', 'Bash');
+        expect(spy).toHaveBeenCalledTimes(1);
+      } finally {
+        spy.mockRestore();
+      }
+    });
+
+    it('evicts the oldest entry once the cache is full (LRU)', () => {
+      for (let i = 0; i < MAX_CACHE_SIZE; i++) {
+        matchesQuery(`^pattern${i}$`, `pattern${i}`);
+      }
+      expect(getMatcherCacheSize()).toBe(MAX_CACHE_SIZE);
+
+      matchesQuery('^overflow$', 'overflow');
+      expect(getMatcherCacheSize()).toBe(MAX_CACHE_SIZE);
+
+      const spy = jest.spyOn(global, 'RegExp');
+      try {
+        matchesQuery('^pattern0$', 'pattern0');
+        expect(spy).toHaveBeenCalledTimes(1);
+      } finally {
+        spy.mockRestore();
+      }
+    });
+
+    it('refreshes LRU position on hit so hot patterns are not evicted', () => {
+      const hotPattern = '^hot$';
+      matchesQuery(hotPattern, 'hot');
+      for (let i = 0; i < MAX_CACHE_SIZE - 1; i++) {
+        matchesQuery(`^cold${i}$`, `cold${i}`);
+      }
+      matchesQuery(hotPattern, 'hot');
+
+      matchesQuery('^overflow$', 'overflow');
+
+      const spy = jest.spyOn(global, 'RegExp');
+      try {
+        matchesQuery(hotPattern, 'hot');
+        expect(spy).not.toHaveBeenCalled();
+      } finally {
+        spy.mockRestore();
+      }
+    });
+  });
+
+  describe('hasNestedQuantifier', () => {
+    it('detects the classic (a+)+ shape', () => {
+      expect(hasNestedQuantifier('(a+)+')).toBe(true);
+      expect(hasNestedQuantifier('(a+)+$')).toBe(true);
+    });
+
+    it('detects (.*)* and (.+)+', () => {
+      expect(hasNestedQuantifier('(.*)*')).toBe(true);
+      expect(hasNestedQuantifier('(.+)+')).toBe(true);
+    });
+
+    it('detects nested quantifier with ? outside', () => {
+      expect(hasNestedQuantifier('(a+)?')).toBe(true);
+    });
+
+    it('detects nested quantifier with {n,} outside', () => {
+      expect(hasNestedQuantifier('(a+){2,}')).toBe(true);
+    });
+
+    it('detects nested quantifier inside deeper groups', () => {
+      expect(hasNestedQuantifier('((a+)+)')).toBe(true);
+      expect(hasNestedQuantifier('prefix(\\w+)+suffix')).toBe(true);
+    });
+
+    it('allows quantifiers that are not nested', () => {
+      expect(hasNestedQuantifier('a+')).toBe(false);
+      expect(hasNestedQuantifier('^Bash$')).toBe(false);
+      expect(hasNestedQuantifier('(a)(b)')).toBe(false);
+      expect(hasNestedQuantifier('(a)+(b)')).toBe(false);
+      expect(hasNestedQuantifier('(ab)+')).toBe(false);
+      expect(hasNestedQuantifier('mcp_\\w+_search')).toBe(false);
+    });
+
+    it('ignores quantifier-looking chars inside character classes', () => {
+      expect(hasNestedQuantifier('([a+b])+')).toBe(false);
+      expect(hasNestedQuantifier('[*+?]+')).toBe(false);
+    });
+
+    it('ignores escaped quantifier characters', () => {
+      expect(hasNestedQuantifier('(\\+)+')).toBe(false);
+      expect(hasNestedQuantifier('(a\\*)+')).toBe(false);
+    });
+
+    describe('group-syntax prefixes are not misread as quantifiers', () => {
+      it('allows non-capturing groups with optional quantifier', () => {
+        expect(hasNestedQuantifier('(?:pre_)?tool_name')).toBe(false);
+        expect(hasNestedQuantifier('(?:ab)?')).toBe(false);
+      });
+
+      it('allows non-capturing groups with + or * quantifier', () => {
+        expect(hasNestedQuantifier('(?:Bash|Shell)+')).toBe(false);
+        expect(hasNestedQuantifier('(?:ab)*')).toBe(false);
+        expect(hasNestedQuantifier('(?:ab){2,5}')).toBe(false);
+      });
+
+      it('allows lookahead and negative lookahead', () => {
+        expect(hasNestedQuantifier('(?=foo)bar')).toBe(false);
+        expect(hasNestedQuantifier('(?!foo)bar')).toBe(false);
+        expect(hasNestedQuantifier('(?=\\w+)bar')).toBe(false);
+      });
+
+      it('allows lookbehind and negative lookbehind', () => {
+        expect(hasNestedQuantifier('(?<=\\s)\\w+')).toBe(false);
+        expect(hasNestedQuantifier('(?<!^)\\w+')).toBe(false);
+      });
+
+      it('allows named capture groups with trailing quantifier', () => {
+        expect(hasNestedQuantifier('(?<name>\\d+)')).toBe(false);
+        expect(hasNestedQuantifier('(?<digits>\\d)+')).toBe(false);
+      });
+    });
+
+    describe('risk propagation across non-capturing wrappers', () => {
+      it('flags (?:(a+))+ — outer quantifier over a wrapped quantified group', () => {
+        expect(hasNestedQuantifier('(?:(a+))+')).toBe(true);
+      });
+
+      it('flags (?:a+)+ — non-capturing group with internal quantifier', () => {
+        expect(hasNestedQuantifier('(?:a+)+')).toBe(true);
+      });
+
+      it('does not flag (?:(ab))+ — quantified wrapper, no inner quantifier', () => {
+        expect(hasNestedQuantifier('(?:(ab))+')).toBe(false);
+      });
+
+      it('flags ((ab)+)+ — multiply-wrapped but contains quantified subgroup', () => {
+        expect(hasNestedQuantifier('((ab)+)+')).toBe(true);
+      });
+    });
+  });
+
+  describe('ReDoS mitigation via matchesQuery', () => {
+    it('rejects nested-quantifier patterns as never-matching', () => {
+      expect(matchesQuery('(a+)+', 'aaaaaaaaaa')).toBe(false);
+      expect(matchesQuery('(.*)*', 'hello')).toBe(false);
+    });
+
+    it('does not stall on an adversarial input that would backtrack', () => {
+      const adversarial = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa!';
+      const start = Date.now();
+      const result = matchesQuery('(a+)+$', adversarial);
+      const elapsed = Date.now() - start;
+      expect(result).toBe(false);
+      expect(elapsed).toBeLessThan(200);
+    });
+  });
+});