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

package/src/graphs/__tests__/MultiAgentGraph.test.ts

@@ -0,0 +1,91 @@
+// src/graphs/__tests__/MultiAgentGraph.test.ts
+import { MultiAgentGraph } from '../MultiAgentGraph';
+import { Providers, EdgeType } from '@/common';
+import type * as t from '@/types';
+
+describe('MultiAgentGraph.validateEdgeAgents', () => {
+  const makeAgent = (agentId: string): t.AgentInputs => ({
+    agentId,
+    provider: Providers.OPENAI,
+    instructions: 'test',
+  });
+
+  it('constructs without error when every edge endpoint has a matching agent', () => {
+    const input: t.MultiAgentGraphInput = {
+      runId: 'r1',
+      agents: [makeAgent('A'), makeAgent('B')],
+      edges: [{ from: 'A', to: 'B', edgeType: EdgeType.HANDOFF }],
+    };
+
+    expect(() => new MultiAgentGraph(input)).not.toThrow();
+  });
+
+  it('throws a descriptive error when an edge `to` points at an unknown agent', () => {
+    const input: t.MultiAgentGraphInput = {
+      runId: 'r1',
+      agents: [makeAgent('A')],
+      edges: [{ from: 'A', to: 'MISSING', edgeType: EdgeType.HANDOFF }],
+    };
+
+    expect(() => new MultiAgentGraph(input)).toThrow(/MISSING/);
+    expect(() => new MultiAgentGraph(input)).toThrow(
+      /edges reference agent\(s\) not present in agents/
+    );
+  });
+
+  it('throws when an edge `from` points at an unknown agent', () => {
+    const input: t.MultiAgentGraphInput = {
+      runId: 'r1',
+      agents: [makeAgent('A')],
+      edges: [{ from: 'MISSING', to: 'A', edgeType: EdgeType.HANDOFF }],
+    };
+
+    expect(() => new MultiAgentGraph(input)).toThrow(/MISSING/);
+  });
+
+  it('reports all unknown agent ids in a single error', () => {
+    const input: t.MultiAgentGraphInput = {
+      runId: 'r1',
+      agents: [makeAgent('A')],
+      edges: [
+        { from: 'A', to: 'B', edgeType: EdgeType.HANDOFF },
+        { from: 'A', to: 'C', edgeType: EdgeType.HANDOFF },
+      ],
+    };
+
+    let thrown: Error | undefined;
+    try {
+      new MultiAgentGraph(input);
+    } catch (err) {
+      thrown = err as Error;
+    }
+    expect(thrown).toBeDefined();
+    expect(thrown!.message).toMatch(/"B"/);
+    expect(thrown!.message).toMatch(/"C"/);
+  });
+
+  it('handles array `from` / `to` fields', () => {
+    const valid: t.MultiAgentGraphInput = {
+      runId: 'r1',
+      agents: [makeAgent('A'), makeAgent('B'), makeAgent('C')],
+      edges: [{ from: ['A'], to: ['B', 'C'], edgeType: EdgeType.DIRECT }],
+    };
+    expect(() => new MultiAgentGraph(valid)).not.toThrow();
+
+    const invalid: t.MultiAgentGraphInput = {
+      runId: 'r1',
+      agents: [makeAgent('A'), makeAgent('B')],
+      edges: [{ from: ['A'], to: ['B', 'C'], edgeType: EdgeType.DIRECT }],
+    };
+    expect(() => new MultiAgentGraph(invalid)).toThrow(/"C"/);
+  });
+
+  it('accepts an empty edges array (single-agent case with no handoffs)', () => {
+    const input: t.MultiAgentGraphInput = {
+      runId: 'r1',
+      agents: [makeAgent('A')],
+      edges: [],
+    };
+    expect(() => new MultiAgentGraph(input)).not.toThrow();
+  });
+});

package/src/graphs/gapFeatures.test.ts

@@ -1,7 +1,7 @@
 /**
  * gapFeatures.test.ts
  *
- * Integration tests for the four LibreChat gap features:
+ * Integration tests for the four gap features:
  * 1. Tool Discovery Caching
  * 2. SummarizationConfig (trigger types, initialSummary)
  * 3. EMA Pruning Calibration

package/src/graphs/index.ts

@@ -1,3 +1,2 @@
 export * from './Graph';
 export * from './MultiAgentGraph';
-export * from './HandoffRegistry';

package/src/graphs/phases/__tests__/memoryFlushPhase.test.ts

@@ -1,7 +1,7 @@
 import { shouldFlushMemory } from '../memoryFlushPhase';
 
 describe('shouldFlushMemory', () => {
-  // Use upstream-aligned defaults: soft=4000, reserve=20000 means a 200k
+  // Use defaults: soft=4000, reserve=20000 means a 200k
   // window fires at 176k. Explicit numbers here keep the test independent
   // from the constants file.
   const base = {

package/src/graphs/phases/memoryFlushPhase.ts

@@ -1,7 +1,7 @@
 /**
  * Memory flush phase — trigger logic + reflection invocation.
  *
- * Ported from upstream's post-turn flush handler. The agent is re-invoked
+ * Ported from the reference implementation's post-turn flush handler. The agent is re-invoked
  * with a reflection system prompt and the `memory_append` tool unlocked;
  * it writes notes to its future self, then the graph returns to normal.
  *
@@ -45,7 +45,7 @@ export interface ShouldFlushInput {
 /**
  * Pure trigger function: fires when the current context is within
  * `softThreshold + reserveFloor` tokens of the model window. Matches
- * upstream's formula.
+ * the standard formula.
  */
 export function shouldFlushMemory(input: ShouldFlushInput): boolean {
   if (

package/src/hooks/HookRegistry.ts

@@ -0,0 +1,208 @@
+// src/hooks/HookRegistry.ts
+import type { HookEvent, HookMatcher } from './types';
+
+/**
+ * Internal matcher storage type.
+ *
+ * Matchers registered via the public `register<E>` API are strictly typed
+ * to a single `E`, but the storage needs one uniform slot type per event.
+ * We store them as `HookMatcher<HookEvent>` and cast once at the variance
+ * boundary — see `ensureList` and `snapshot` below. The invariant (every
+ * matcher in `bucket[event]` was registered with that exact event) is
+ * enforced by the public API; breaking it requires bypassing the types.
+ */
+type MatcherBucket = Partial<Record<HookEvent, HookMatcher<HookEvent>[]>>;
+
+/**
+ * Run-scoped storage for hook matchers with an additional layer for
+ * session-scoped matchers that should be cleaned up between sessions.
+ *
+ * Hosts construct one registry per `Run` (mirroring how `HandlerRegistry` is
+ * scoped) and register global matchers + per-session matchers against it.
+ * Registration is strictly additive — nothing in this class mutates a
+ * matcher's callbacks or flags after insertion.
+ *
+ * ## Why `Map<sessionId, MatcherBucket>` and not `Record`
+ *
+ * Real consumers run thousands of parallel sessions in one Node process, and
+ * hook registration happens inside hot paths (tool loading, agent spawning).
+ * A `Record<sessionId, ...>` has to be spread on every insertion, which is
+ * O(n) per call and O(n²) total for a batch of parallel registrations. A
+ * Map mutates in place, keeping insertions O(1). This mirrors the reasoning
+ * Claude Code documents at `utils/hooks/sessionHooks.ts:62`.
+ */
+export class HookRegistry {
+  private readonly global: MatcherBucket = {};
+  private readonly sessions: Map<string, MatcherBucket> = new Map();
+
+  /**
+   * Register a matcher for the lifetime of this registry (= one Run).
+   * Returns an unregister function that removes the matcher by reference.
+   */
+  register<E extends HookEvent>(event: E, matcher: HookMatcher<E>): () => void {
+    const list = ensureList(this.global, event);
+    list.push(widen(matcher));
+    return () => {
+      removeFromList(list, matcher);
+    };
+  }
+
+  /**
+   * Register a matcher for a specific session. Cleared automatically when
+   * `clearSession(sessionId)` is called, or can be removed directly via the
+   * returned unregister function.
+   */
+  registerSession<E extends HookEvent>(
+    sessionId: string,
+    event: E,
+    matcher: HookMatcher<E>
+  ): () => void {
+    const bucket = this.ensureSessionBucket(sessionId);
+    const list = ensureList(bucket, event);
+    list.push(widen(matcher));
+    return () => {
+      removeFromList(list, matcher);
+    };
+  }
+
+  /**
+   * Returns all matchers registered for `event`, concatenating global first
+   * and then session-specific (when `sessionId` is supplied). The caller
+   * receives a fresh array, so iterating it is safe even if a matcher is
+   * removed mid-iteration (e.g. via `once: true`).
+   */
+  getMatchers<E extends HookEvent>(
+    event: E,
+    sessionId?: string
+  ): HookMatcher<E>[] {
+    const globalList = readList(this.global, event);
+    if (sessionId === undefined) {
+      return snapshot<E>(globalList);
+    }
+    const bucket = this.sessions.get(sessionId);
+    if (bucket === undefined) {
+      return snapshot<E>(globalList);
+    }
+    const sessionList = readList(bucket, event);
+    if (globalList.length === 0) {
+      return snapshot<E>(sessionList);
+    }
+    if (sessionList.length === 0) {
+      return snapshot<E>(globalList);
+    }
+    return snapshot<E>([...globalList, ...sessionList]);
+  }
+
+  /**
+   * Removes `matcher` by reference from global storage first, falling back
+   * to the session bucket when `sessionId` is supplied. Used by
+   * `executeHooks` to drop `once: true` matchers after they fire.
+   */
+  removeMatcher<E extends HookEvent>(
+    event: E,
+    matcher: HookMatcher<E>,
+    sessionId?: string
+  ): boolean {
+    if (removeFromList(readList(this.global, event), matcher)) {
+      return true;
+    }
+    if (sessionId === undefined) {
+      return false;
+    }
+    const bucket = this.sessions.get(sessionId);
+    if (bucket === undefined) {
+      return false;
+    }
+    return removeFromList(readList(bucket, event), matcher);
+  }
+
+  /**
+   * Drops every session-scoped matcher for `sessionId`. Call this in the
+   * `finally` block around a Run so a `once: true` hook that never fired
+   * cannot leak into the next session on the same registry.
+   */
+  clearSession(sessionId: string): void {
+    this.sessions.delete(sessionId);
+  }
+
+  /** True if at least one matcher exists for `event` (global + session). */
+  hasHookFor(event: HookEvent, sessionId?: string): boolean {
+    if (readList(this.global, event).length > 0) {
+      return true;
+    }
+    if (sessionId === undefined) {
+      return false;
+    }
+    const bucket = this.sessions.get(sessionId);
+    if (bucket === undefined) {
+      return false;
+    }
+    return readList(bucket, event).length > 0;
+  }
+
+  private ensureSessionBucket(sessionId: string): MatcherBucket {
+    const existing = this.sessions.get(sessionId);
+    if (existing !== undefined) {
+      return existing;
+    }
+    const fresh: MatcherBucket = {};
+    this.sessions.set(sessionId, fresh);
+    return fresh;
+  }
+}
+
+function ensureList(
+  bucket: MatcherBucket,
+  event: HookEvent
+): HookMatcher<HookEvent>[] {
+  const existing = bucket[event];
+  if (existing !== undefined) {
+    return existing;
+  }
+  const fresh: HookMatcher<HookEvent>[] = [];
+  bucket[event] = fresh;
+  return fresh;
+}
+
+function readList(
+  bucket: MatcherBucket,
+  event: HookEvent
+): HookMatcher<HookEvent>[] {
+  return bucket[event] ?? [];
+}
+
+function removeFromList<E extends HookEvent>(
+  list: HookMatcher<HookEvent>[],
+  matcher: HookMatcher<E>
+): boolean {
+  const idx = list.indexOf(widen(matcher));
+  if (idx < 0) {
+    return false;
+  }
+  list.splice(idx, 1);
+  return true;
+}
+
+/**
+ * Widen a per-event matcher to the storage's uniform slot type. Unsound at
+ * the type level (function parameters are contravariant) but safe by
+ * construction: `HookRegistry.register<E>` only ever puts matchers into the
+ * bucket slot for their own event, and reads go through `snapshot<E>`
+ * which is only called with the same `E`.
+ */
+function widen<E extends HookEvent>(
+  matcher: HookMatcher<E>
+): HookMatcher<HookEvent> {
+  return matcher as unknown as HookMatcher<HookEvent>;
+}
+
+/**
+ * Narrow a storage list back to a per-event matcher list on the way out.
+ * Sound counterpart to `widen`: the list only contains matchers that were
+ * registered against `E`, because the public API enforces it on insert.
+ */
+function snapshot<E extends HookEvent>(
+  list: readonly HookMatcher<HookEvent>[]
+): HookMatcher<E>[] {
+  return list.slice() as unknown as HookMatcher<E>[];
+}

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

@@ -0,0 +1,190 @@
+// src/hooks/__tests__/HookRegistry.test.ts
+import { HookRegistry } from '../HookRegistry';
+import type {
+  HookMatcher,
+  HookCallback,
+  PreToolUseHookOutput,
+  PostToolUseHookOutput,
+} from '../types';
+
+const noop: HookCallback<
+  'PreToolUse'
+> = async (): Promise<PreToolUseHookOutput> => ({});
+const noopPost: HookCallback<
+  'PostToolUse'
+> = async (): Promise<PostToolUseHookOutput> => ({});
+
+function makePreToolUseMatcher(pattern?: string): HookMatcher<'PreToolUse'> {
+  return {
+    pattern,
+    hooks: [noop],
+  };
+}
+
+function makePostToolUseMatcher(): HookMatcher<'PostToolUse'> {
+  return {
+    hooks: [noopPost],
+  };
+}
+
+describe('HookRegistry', () => {
+  describe('global registration', () => {
+    it('stores a matcher and returns it via getMatchers', () => {
+      const registry = new HookRegistry();
+      const matcher = makePreToolUseMatcher('Bash');
+      registry.register('PreToolUse', matcher);
+      const matchers = registry.getMatchers('PreToolUse');
+      expect(matchers).toHaveLength(1);
+      expect(matchers[0]).toBe(matcher);
+    });
+
+    it('keeps registrations isolated across events', () => {
+      const registry = new HookRegistry();
+      const pre = makePreToolUseMatcher('Bash');
+      const post = makePostToolUseMatcher();
+      registry.register('PreToolUse', pre);
+      registry.register('PostToolUse', post);
+      expect(registry.getMatchers('PreToolUse')).toEqual([pre]);
+      expect(registry.getMatchers('PostToolUse')).toEqual([post]);
+      expect(registry.getMatchers('Stop')).toEqual([]);
+    });
+
+    it('unregister removes the matcher from the registry', () => {
+      const registry = new HookRegistry();
+      const matcher = makePreToolUseMatcher();
+      const unregister = registry.register('PreToolUse', matcher);
+      expect(registry.getMatchers('PreToolUse')).toHaveLength(1);
+      unregister();
+      expect(registry.getMatchers('PreToolUse')).toHaveLength(0);
+    });
+
+    it('hasHookFor reflects registration state', () => {
+      const registry = new HookRegistry();
+      expect(registry.hasHookFor('PreToolUse')).toBe(false);
+      registry.register('PreToolUse', makePreToolUseMatcher());
+      expect(registry.hasHookFor('PreToolUse')).toBe(true);
+      expect(registry.hasHookFor('PostToolUse')).toBe(false);
+    });
+
+    it('supports multiple matchers on the same event', () => {
+      const registry = new HookRegistry();
+      const a = makePreToolUseMatcher('Bash');
+      const b = makePreToolUseMatcher('Edit');
+      registry.register('PreToolUse', a);
+      registry.register('PreToolUse', b);
+      const matchers = registry.getMatchers('PreToolUse');
+      expect(matchers).toHaveLength(2);
+      expect(matchers).toContain(a);
+      expect(matchers).toContain(b);
+    });
+
+    it('returns a fresh array on each getMatchers call', () => {
+      const registry = new HookRegistry();
+      registry.register('PreToolUse', makePreToolUseMatcher());
+      const first = registry.getMatchers('PreToolUse');
+      const second = registry.getMatchers('PreToolUse');
+      expect(first).not.toBe(second);
+      first.length = 0;
+      expect(registry.getMatchers('PreToolUse')).toHaveLength(1);
+    });
+  });
+
+  describe('session registration', () => {
+    it('scopes matchers to a single session', () => {
+      const registry = new HookRegistry();
+      const sessionA = makePreToolUseMatcher('Bash');
+      const sessionB = makePreToolUseMatcher('Edit');
+      registry.registerSession('run-a', 'PreToolUse', sessionA);
+      registry.registerSession('run-b', 'PreToolUse', sessionB);
+
+      expect(registry.getMatchers('PreToolUse', 'run-a')).toEqual([sessionA]);
+      expect(registry.getMatchers('PreToolUse', 'run-b')).toEqual([sessionB]);
+      expect(registry.getMatchers('PreToolUse')).toEqual([]);
+    });
+
+    it('merges global matchers in front of session matchers', () => {
+      const registry = new HookRegistry();
+      const global = makePreToolUseMatcher('global');
+      const session = makePreToolUseMatcher('session');
+      registry.register('PreToolUse', global);
+      registry.registerSession('run-a', 'PreToolUse', session);
+
+      const matchers = registry.getMatchers('PreToolUse', 'run-a');
+      expect(matchers).toEqual([global, session]);
+    });
+
+    it('clearSession drops only the given session', () => {
+      const registry = new HookRegistry();
+      const a = makePreToolUseMatcher('a');
+      const b = makePreToolUseMatcher('b');
+      registry.registerSession('run-a', 'PreToolUse', a);
+      registry.registerSession('run-b', 'PreToolUse', b);
+
+      registry.clearSession('run-a');
+      expect(registry.getMatchers('PreToolUse', 'run-a')).toEqual([]);
+      expect(registry.getMatchers('PreToolUse', 'run-b')).toEqual([b]);
+    });
+
+    it('removeMatcher removes from the correct scope', () => {
+      const registry = new HookRegistry();
+      const global = makePreToolUseMatcher('global');
+      const session = makePreToolUseMatcher('session');
+      registry.register('PreToolUse', global);
+      registry.registerSession('run-a', 'PreToolUse', session);
+
+      expect(registry.removeMatcher('PreToolUse', session, 'run-a')).toBe(true);
+      expect(registry.getMatchers('PreToolUse', 'run-a')).toEqual([global]);
+
+      expect(registry.removeMatcher('PreToolUse', global)).toBe(true);
+      expect(registry.getMatchers('PreToolUse', 'run-a')).toEqual([]);
+    });
+
+    it('removeMatcher returns false when the matcher is not found', () => {
+      const registry = new HookRegistry();
+      const orphan = makePreToolUseMatcher('orphan');
+      expect(registry.removeMatcher('PreToolUse', orphan)).toBe(false);
+      expect(registry.removeMatcher('PreToolUse', orphan, 'run-a')).toBe(false);
+    });
+
+    it('session unregister function removes only that matcher', () => {
+      const registry = new HookRegistry();
+      const a = makePreToolUseMatcher('a');
+      const b = makePreToolUseMatcher('b');
+      const unregisterA = registry.registerSession('run-a', 'PreToolUse', a);
+      registry.registerSession('run-a', 'PreToolUse', b);
+
+      unregisterA();
+      expect(registry.getMatchers('PreToolUse', 'run-a')).toEqual([b]);
+    });
+
+    it('hasHookFor honours the sessionId parameter', () => {
+      const registry = new HookRegistry();
+      registry.registerSession('run-a', 'PreToolUse', makePreToolUseMatcher());
+      expect(registry.hasHookFor('PreToolUse')).toBe(false);
+      expect(registry.hasHookFor('PreToolUse', 'run-a')).toBe(true);
+      expect(registry.hasHookFor('PreToolUse', 'run-b')).toBe(false);
+    });
+  });
+
+  describe('session isolation under parallel registration', () => {
+    it('does not leak matchers between sessions registered in parallel', async () => {
+      const registry = new HookRegistry();
+      const sessions = Array.from({ length: 50 }, (_, i) => `run-${i}`);
+      await Promise.all(
+        sessions.map(async (sid): Promise<void> => {
+          registry.registerSession(
+            sid,
+            'PreToolUse',
+            makePreToolUseMatcher(sid)
+          );
+        })
+      );
+
+      for (const sid of sessions) {
+        const matchers = registry.getMatchers('PreToolUse', sid);
+        expect(matchers).toHaveLength(1);
+        expect(matchers[0]?.pattern).toBe(sid);
+      }
+    });
+  });
+});