@illuma-ai/agents 1.1.28 → 1.3.0

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

@@ -0,0 +1,264 @@
+/**
+ * Unit tests for the agentic flush loop.
+ *
+ * Scope: pure loop mechanics — model invocation, tool dispatch,
+ * ToolMessage feedback, iteration cap, NO_REPLY detection, error capture.
+ * Does NOT touch the real pgvector backend or memory_append — every tool
+ * is a stub so the test stays hermetic.
+ */
+import { AIMessage, HumanMessage } from '@langchain/core/messages';
+import { tool } from '@langchain/core/tools';
+import { z } from 'zod';
+import {
+  runFlushLoop,
+  extractText,
+  parseToolResult,
+  type InvokableModel,
+} from '../flushLoop';
+import {
+  MEMORY_APPEND_TOOL_NAME,
+  SILENT_REPLY_TOKEN,
+} from '@/memory/constants';
+
+/**
+ * Build a stubbed LangChain tool with a controllable response
+ * function, so individual test cases can simulate success / schema
+ * error / backend error.
+ */
+function makeAppendStub(
+  respond: (args: { path: string; content: string }) => string
+) {
+  return tool(
+    async (args) => respond(args as { path: string; content: string }),
+    {
+      name: MEMORY_APPEND_TOOL_NAME,
+      description: 'stub memory_append',
+      schema: z.object({ path: z.string(), content: z.string() }),
+    }
+  );
+}
+
+/** Scripted model — returns pre-canned AIMessages in order. */
+function scriptedModel(script: AIMessage[]): InvokableModel {
+  let i = 0;
+  return {
+    async invoke() {
+      const next = script[i] ?? new AIMessage({ content: 'done' });
+      i += 1;
+      return next;
+    },
+  };
+}
+
+describe('runFlushLoop', () => {
+  it('stops immediately if the first response has no tool_calls', async () => {
+    const model = scriptedModel([
+      new AIMessage({ content: 'nothing to store' }),
+    ]);
+    const result = await runFlushLoop({
+      model,
+      tools: [],
+      initialMessages: [new HumanMessage('flush')],
+    });
+    expect(result.iterations).toBe(1);
+    expect(result.appendsAttempted).toBe(0);
+    expect(result.appendsSucceeded).toBe(0);
+    expect(result.toolErrors).toEqual([]);
+    expect(result.silentReply).toBe(false);
+    expect(result.finalText).toBe('nothing to store');
+  });
+
+  it('detects NO_REPLY silent reply', async () => {
+    const model = scriptedModel([
+      new AIMessage({ content: SILENT_REPLY_TOKEN }),
+    ]);
+    const result = await runFlushLoop({
+      model,
+      tools: [],
+      initialMessages: [new HumanMessage('flush')],
+    });
+    expect(result.silentReply).toBe(true);
+    expect(result.finalText).toBe(SILENT_REPLY_TOKEN);
+  });
+
+  it('executes memory_append tool_calls and counts successes', async () => {
+    const appendTool = makeAppendStub(({ path }) =>
+      JSON.stringify({ ok: true, path })
+    );
+    const model = scriptedModel([
+      new AIMessage({
+        content: '',
+        tool_calls: [
+          {
+            name: MEMORY_APPEND_TOOL_NAME,
+            args: { path: 'memory/2026-04-13.md', content: 'user prefers X' },
+            id: 'c1',
+          },
+          {
+            name: MEMORY_APPEND_TOOL_NAME,
+            args: {
+              path: 'memory/2026-04-13.md',
+              content: 'tool schema failed',
+            },
+            id: 'c2',
+          },
+        ],
+      }),
+      new AIMessage({ content: SILENT_REPLY_TOKEN }),
+    ]);
+    const result = await runFlushLoop({
+      model,
+      tools: [appendTool],
+      initialMessages: [new HumanMessage('flush')],
+    });
+    expect(result.iterations).toBe(2);
+    expect(result.appendsAttempted).toBe(2);
+    expect(result.appendsSucceeded).toBe(2);
+    expect(result.silentReply).toBe(true);
+    expect(result.toolErrors).toEqual([]);
+  });
+
+  it('captures tool errors and feeds them back as ToolMessages', async () => {
+    const appendTool = makeAppendStub(() =>
+      JSON.stringify({ ok: false, error: 'path must start with memory/' })
+    );
+    const model = scriptedModel([
+      new AIMessage({
+        content: '',
+        tool_calls: [
+          {
+            name: MEMORY_APPEND_TOOL_NAME,
+            args: { path: 'invalid.md', content: 'x' },
+            id: 'bad1',
+          },
+        ],
+      }),
+      new AIMessage({ content: 'gave up' }),
+    ]);
+    const result = await runFlushLoop({
+      model,
+      tools: [appendTool],
+      initialMessages: [new HumanMessage('flush')],
+    });
+    expect(result.appendsAttempted).toBe(1);
+    expect(result.appendsSucceeded).toBe(0);
+    expect(result.toolErrors).toHaveLength(1);
+    expect(result.toolErrors[0].error).toMatch(/path must start with memory/);
+    // The ToolMessage should be in the transcript so the next invoke
+    // would see it.
+    const hasToolMsg = result.messages.some((m) => m._getType() === 'tool');
+    expect(hasToolMsg).toBe(true);
+  });
+
+  it('records tool_not_found when the model calls an unknown tool', async () => {
+    const model = scriptedModel([
+      new AIMessage({
+        content: '',
+        tool_calls: [{ name: 'mystery_tool', args: {}, id: 'm1' }],
+      }),
+      new AIMessage({ content: 'stopped' }),
+    ]);
+    const result = await runFlushLoop({
+      model,
+      tools: [],
+      initialMessages: [new HumanMessage('flush')],
+    });
+    expect(result.toolErrors).toHaveLength(1);
+    expect(result.toolErrors[0].error).toMatch(/tool_not_found/);
+  });
+
+  it('stops at maxIterations and flags hitIterationCap', async () => {
+    // A model that keeps emitting tool_calls forever.
+    const appendTool = makeAppendStub(() =>
+      JSON.stringify({ ok: true, path: 'memory/x.md' })
+    );
+    const model: InvokableModel = {
+      async invoke() {
+        return new AIMessage({
+          content: '',
+          tool_calls: [
+            {
+              name: MEMORY_APPEND_TOOL_NAME,
+              args: { path: 'memory/x.md', content: 'loop' },
+              id: 'loop',
+            },
+          ],
+        });
+      },
+    };
+    const result = await runFlushLoop({
+      model,
+      tools: [appendTool],
+      initialMessages: [new HumanMessage('flush')],
+      maxIterations: 3,
+    });
+    expect(result.iterations).toBe(3);
+    expect(result.hitIterationCap).toBe(true);
+    expect(result.appendsAttempted).toBe(3);
+    expect(result.appendsSucceeded).toBe(3);
+  });
+
+  it('surfaces thrown tool errors without aborting the loop', async () => {
+    const appendTool = makeAppendStub(() => {
+      throw new Error('backend down');
+    });
+    const model = scriptedModel([
+      new AIMessage({
+        content: '',
+        tool_calls: [
+          {
+            name: MEMORY_APPEND_TOOL_NAME,
+            args: { path: 'memory/x.md', content: 'x' },
+            id: 't1',
+          },
+        ],
+      }),
+      new AIMessage({ content: 'done' }),
+    ]);
+    const result = await runFlushLoop({
+      model,
+      tools: [appendTool],
+      initialMessages: [new HumanMessage('flush')],
+    });
+    expect(result.appendsAttempted).toBe(1);
+    expect(result.appendsSucceeded).toBe(0);
+    expect(result.toolErrors[0].error).toMatch(/backend down/);
+    expect(result.iterations).toBe(2);
+  });
+});
+
+describe('extractText', () => {
+  it('returns string content directly', () => {
+    expect(extractText(new AIMessage({ content: 'hi' }))).toBe('hi');
+  });
+
+  it('joins array content blocks', () => {
+    const ai = new AIMessage({
+      content: [
+        { type: 'text', text: 'hello ' },
+        { type: 'text', text: 'world' },
+      ] as unknown as string,
+    });
+    expect(extractText(ai)).toBe('hello world');
+  });
+});
+
+describe('parseToolResult', () => {
+  it('parses well-formed JSON with ok field', () => {
+    expect(parseToolResult('{"ok":true,"path":"memory/x.md"}')).toEqual({
+      ok: true,
+      path: 'memory/x.md',
+    });
+  });
+
+  it('parses error JSON', () => {
+    expect(parseToolResult('{"ok":false,"error":"bad"}')).toEqual({
+      ok: false,
+      error: 'bad',
+    });
+  });
+
+  it('treats non-JSON as opaque success', () => {
+    expect(parseToolResult('hello')).toEqual({ ok: true });
+  });
+});

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

@@ -0,0 +1,37 @@
+import { shouldFlushMemory } from '../memoryFlushPhase';
+
+describe('shouldFlushMemory', () => {
+  // Use upstream-aligned 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 = {
+    windowTokens: 200_000,
+    reserveFloorTokens: 20_000,
+    softThresholdTokens: 4_000,
+  };
+
+  it('returns false far from the window', () => {
+    expect(shouldFlushMemory({ ...base, currentTokens: 100_000 })).toBe(false);
+  });
+
+  it('returns true exactly at the threshold', () => {
+    // window - reserve - soft = 176_000
+    expect(shouldFlushMemory({ ...base, currentTokens: 176_000 })).toBe(true);
+  });
+
+  it('returns true past the threshold', () => {
+    expect(shouldFlushMemory({ ...base, currentTokens: 190_000 })).toBe(true);
+  });
+
+  it('returns false for non-finite inputs', () => {
+    expect(shouldFlushMemory({ ...base, currentTokens: Number.NaN })).toBe(
+      false
+    );
+  });
+
+  it('returns false when window is zero', () => {
+    expect(shouldFlushMemory({ currentTokens: 100, windowTokens: 0 })).toBe(
+      false
+    );
+  });
+});

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

@@ -0,0 +1,150 @@
+/**
+ * Integration-lite test for {@link runMemoryFlush}: scripted model +
+ * in-memory backend stub. Verifies end-to-end that the flush phase
+ * flips, tool_calls execute, the backend sees the writes, and the
+ * rich result object is populated.
+ */
+import { AIMessage } from '@langchain/core/messages';
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { runMemoryFlush } from '../memoryFlushPhase';
+import type {
+  MemoryAppendInput,
+  MemoryBackend,
+  MemoryScope,
+} from '@/memory/types';
+import {
+  MEMORY_APPEND_TOOL_NAME,
+  MEMORY_PHASE_FLUSHING,
+  MEMORY_PHASE_NORMAL,
+  SILENT_REPLY_TOKEN,
+} from '@/memory/constants';
+
+/** Minimal in-memory backend — just records appends. */
+function makeBackend(): MemoryBackend & { writes: MemoryAppendInput[] } {
+  const writes: MemoryAppendInput[] = [];
+  return {
+    kind: 'vector',
+    writes,
+    async search() {
+      return [];
+    },
+    async get() {
+      return null;
+    },
+    async append(_scope: MemoryScope, input: MemoryAppendInput) {
+      writes.push(input);
+    },
+    async health() {
+      return { ok: true, backend: 'vector' };
+    },
+  };
+}
+
+/**
+ * Scripted model masquerading as a BaseChatModel. We only need
+ * `invoke` and `bindTools`; the memoryFlushPhase code accesses those
+ * through bindToolsIfSupported and runFlushLoop only.
+ */
+function scriptedModel(script: AIMessage[]) {
+  let i = 0;
+  const model = {
+    bindTools() {
+      return model;
+    },
+    async invoke() {
+      const next = script[i] ?? new AIMessage({ content: SILENT_REPLY_TOKEN });
+      i += 1;
+      return next;
+    },
+  };
+  return model as unknown as BaseChatModel;
+}
+
+describe('runMemoryFlush', () => {
+  it('flips phase, runs the loop, and writes notes through the backend', async () => {
+    const backend = makeBackend();
+    const phases: string[] = [];
+    const setPhase = (
+      p: typeof MEMORY_PHASE_NORMAL | typeof MEMORY_PHASE_FLUSHING
+    ) => {
+      phases.push(p);
+    };
+
+    const model = scriptedModel([
+      new AIMessage({
+        content: '',
+        tool_calls: [
+          {
+            name: MEMORY_APPEND_TOOL_NAME,
+            args: {
+              path: 'memory/user/preferences.md',
+              content: 'User is Varun; prefers clean agent separation.',
+            },
+            id: 'c1',
+          },
+        ],
+      }),
+      new AIMessage({ content: SILENT_REPLY_TOKEN }),
+    ]);
+
+    const result = await runMemoryFlush({
+      model,
+      memory: {
+        backend,
+        scope: { agentId: 'orchestrator', userId: 'user-1' },
+      },
+      conversationSummary: 'Varun explained his preferences...',
+      setPhase,
+    });
+
+    expect(result.ran).toBe(true);
+    expect(result.iterations).toBe(2);
+    expect(result.appendsAttempted).toBe(1);
+    expect(result.appendsSucceeded).toBe(1);
+    expect(result.silentReply).toBe(true);
+    expect(result.toolErrors).toEqual([]);
+    expect(backend.writes).toHaveLength(1);
+    expect(backend.writes[0].path).toBe('memory/user/preferences.md');
+    expect(phases[0]).toBe(MEMORY_PHASE_FLUSHING);
+    expect(phases[phases.length - 1]).toBe(MEMORY_PHASE_NORMAL);
+  });
+
+  it('returns ran=false when flush is disabled', async () => {
+    const backend = makeBackend();
+    const result = await runMemoryFlush({
+      model: scriptedModel([]),
+      memory: {
+        backend,
+        scope: { agentId: 'a', userId: 'u' },
+        flush: { enabled: false },
+      },
+      conversationSummary: 'x',
+      setPhase: () => {},
+    });
+    expect(result.ran).toBe(false);
+    expect(backend.writes).toHaveLength(0);
+  });
+
+  it('restores phase even when the model throws', async () => {
+    const backend = makeBackend();
+    const phases: string[] = [];
+    const brokenModel = {
+      bindTools() {
+        return brokenModel;
+      },
+      async invoke() {
+        throw new Error('boom');
+      },
+    } as unknown as BaseChatModel;
+
+    const result = await runMemoryFlush({
+      model: brokenModel,
+      memory: { backend, scope: { agentId: 'a', userId: 'u' } },
+      conversationSummary: 'x',
+      setPhase: (p) => phases.push(p),
+    });
+    expect(result.ran).toBe(false);
+    expect(result.error).toMatch(/boom/);
+    expect(phases[phases.length - 1]).toBe(MEMORY_PHASE_NORMAL);
+  });
+});