@illuma-ai/agents 1.1.25 → 1.3.0

package/src/graphs/phases/flushLoop.ts

@@ -0,0 +1,303 @@
+/**
+ * Agentic tool-execution loop for the memory-flush reflection turn.
+ *
+ * Extracted from {@link runMemoryFlush} so the loop primitive is
+ * testable in isolation and reusable from any reflection-style phase
+ * that wants "invoke → execute tool_calls → feed results back → repeat".
+ *
+ * Design:
+ * - Bounded iterations — caller passes `maxIterations` (default
+ *   {@link DEFAULT_MAX_FLUSH_ITERATIONS}). The loop exits as soon as
+ *   the model stops emitting `tool_calls`, hits the cap, or the reply
+ *   matches {@link SILENT_REPLY_TOKEN}.
+ * - Rich result — returns iteration count, attempted/successful
+ *   appends, per-tool errors, silent-reply flag, and raw final text.
+ *   The caller logs this; nothing is swallowed.
+ * - Self-contained tool execution — does not depend on LangGraph's
+ *   ToolNode or any graph runtime. The only contract is the
+ *   LangChain v0.3 `StructuredToolInterface.invoke(args)` shape.
+ * - Tool errors are captured as {@link ToolMessage}s with the raw
+ *   JSON error, so the model can read them and self-correct (e.g.
+ *   retry with a different path if the schema rejected its first
+ *   attempt).
+ */
+import {
+  AIMessage,
+  type BaseMessage,
+  ToolMessage,
+} from '@langchain/core/messages';
+import type { StructuredToolInterface } from '@langchain/core/tools';
+import {
+  DEFAULT_MAX_FLUSH_ITERATIONS,
+  MEMORY_APPEND_TOOL_NAME,
+  SILENT_REPLY_TOKEN,
+} from '@/memory/constants';
+
+/** Minimal model contract the loop needs. */
+export interface InvokableModel {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  invoke(messages: BaseMessage[], options?: any): Promise<AIMessage>;
+}
+
+export interface FlushLoopParams {
+  model: InvokableModel;
+  tools: StructuredToolInterface[];
+  /** Initial messages — typically [SystemMessage, HumanMessage]. */
+  initialMessages: BaseMessage[];
+  /** Upper bound on model.invoke() calls. Default 8. */
+  maxIterations?: number;
+  /**
+   * Optional debug hook — called once per iteration with `{ i, ai, toolCalls }`.
+   * Use for INFO-level tracing during rollout; pass `undefined` in prod.
+   */
+  onIteration?: (event: {
+    i: number;
+    ai: AIMessage;
+    toolCalls: ToolCallLike[];
+  }) => void;
+}
+
+/** Shape LangChain emits on AIMessage.tool_calls (duck-typed). */
+export interface ToolCallLike {
+  name: string;
+  args: Record<string, unknown>;
+  id?: string;
+}
+
+export interface ToolErrorRecord {
+  iteration: number;
+  toolName: string;
+  toolCallId?: string;
+  error: string;
+  /** Raw args the model passed — useful for diagnosing schema drift. */
+  args?: Record<string, unknown>;
+}
+
+export interface FlushLoopResult {
+  /** Number of model.invoke() calls actually made. */
+  iterations: number;
+  /** Every `memory_append` tool_call the model emitted across all iterations. */
+  appendsAttempted: number;
+  /** How many of those returned `{ ok: true, ... }`. */
+  appendsSucceeded: number;
+  /** Tool errors the model saw (and may have reacted to). */
+  toolErrors: ToolErrorRecord[];
+  /** True if the final AIMessage text matched {@link SILENT_REPLY_TOKEN}. */
+  silentReply: boolean;
+  /** Whether the loop stopped because it hit `maxIterations`. */
+  hitIterationCap: boolean;
+  /** Final AIMessage content as plain text (best-effort). */
+  finalText: string;
+  /** Full message transcript — useful for debugging / tests. */
+  messages: BaseMessage[];
+}
+
+/**
+ * Extract a flat text string from any AIMessage content shape
+ * (string, array of content blocks, etc).
+ */
+export function extractText(message: AIMessage): string {
+  const c = message.content;
+  if (typeof c === 'string') return c;
+  if (!Array.isArray(c)) return '';
+  return c
+    .map((block) => {
+      if (typeof block === 'string') return block;
+      if (block && typeof block === 'object' && 'text' in block) {
+        return String((block as { text?: unknown }).text ?? '');
+      }
+      return '';
+    })
+    .join('')
+    .trim();
+}
+
+/**
+ * Parse a tool result string. Memory tools return JSON with
+ * `{ ok: boolean, error?: string, path?: string }`. Non-JSON payloads
+ * are treated as opaque success strings.
+ */
+export function parseToolResult(raw: string): {
+  ok: boolean;
+  error?: string;
+  path?: string;
+} {
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && 'ok' in parsed) {
+      return {
+        ok: Boolean(parsed.ok),
+        error: typeof parsed.error === 'string' ? parsed.error : undefined,
+        path: typeof parsed.path === 'string' ? parsed.path : undefined,
+      };
+    }
+    return { ok: true };
+  } catch {
+    return { ok: true };
+  }
+}
+
+/**
+ * Bind a tool array to a model if `bindTools` exists on the model.
+ * Exported so the caller (runMemoryFlush) can do it once and pass the
+ * bound model in, keeping this loop free of LangChain model-specific
+ * extensions.
+ */
+export function bindToolsIfSupported(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  model: any,
+  tools: StructuredToolInterface[]
+): InvokableModel {
+  if (typeof model?.bindTools === 'function') {
+    return model.bindTools(tools) as InvokableModel;
+  }
+  return model as InvokableModel;
+}
+
+/**
+ * Run the agentic reflection loop until the model stops emitting
+ * tool_calls, the iteration cap is hit, or the final reply matches
+ * {@link SILENT_REPLY_TOKEN}.
+ */
+export async function runFlushLoop(
+  params: FlushLoopParams
+): Promise<FlushLoopResult> {
+  const {
+    model,
+    tools,
+    initialMessages,
+    maxIterations = DEFAULT_MAX_FLUSH_ITERATIONS,
+    onIteration,
+  } = params;
+
+  const toolMap = new Map<string, StructuredToolInterface>();
+  for (const t of tools) {
+    toolMap.set(t.name, t);
+  }
+
+  const messages: BaseMessage[] = [...initialMessages];
+  const toolErrors: ToolErrorRecord[] = [];
+  let appendsAttempted = 0;
+  let appendsSucceeded = 0;
+  let iterations = 0;
+  let finalText = '';
+  let hitIterationCap = false;
+  // Tracks whether the most recent iteration ended with unresolved
+  // tool_calls. If we exit the while via the cap (not via the natural
+  // `break`), this stays true and we flag hitIterationCap.
+  let lastIterationHadPendingCalls = false;
+
+  while (iterations < maxIterations) {
+    iterations += 1;
+    const ai = await model.invoke(messages);
+    messages.push(ai);
+
+    const toolCalls = (ai.tool_calls ?? []) as ToolCallLike[];
+    onIteration?.({ i: iterations, ai, toolCalls });
+
+    if (toolCalls.length === 0) {
+      finalText = extractText(ai);
+      lastIterationHadPendingCalls = false;
+      break;
+    }
+    lastIterationHadPendingCalls = true;
+
+    for (const call of toolCalls) {
+      if (call.name === MEMORY_APPEND_TOOL_NAME) {
+        appendsAttempted += 1;
+      }
+      const tool = toolMap.get(call.name);
+      if (!tool) {
+        const errStr = `tool_not_found: ${call.name}`;
+        toolErrors.push({
+          iteration: iterations,
+          toolName: call.name,
+          toolCallId: call.id,
+          error: errStr,
+          args: call.args,
+        });
+        messages.push(
+          new ToolMessage({
+            content: JSON.stringify({ ok: false, error: errStr }),
+            tool_call_id: call.id ?? '',
+            name: call.name,
+          })
+        );
+        continue;
+      }
+
+      let rawResult: string;
+      try {
+        // LangChain tools accept the parsed args object.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const res = await (tool as any).invoke(call.args);
+        rawResult = typeof res === 'string' ? res : JSON.stringify(res);
+      } catch (err) {
+        const errStr = err instanceof Error ? err.message : String(err);
+        toolErrors.push({
+          iteration: iterations,
+          toolName: call.name,
+          toolCallId: call.id,
+          error: errStr,
+          args: call.args,
+        });
+        messages.push(
+          new ToolMessage({
+            content: JSON.stringify({ ok: false, error: errStr }),
+            tool_call_id: call.id ?? '',
+            name: call.name,
+          })
+        );
+        continue;
+      }
+
+      const parsed = parseToolResult(rawResult);
+      if (call.name === MEMORY_APPEND_TOOL_NAME) {
+        if (parsed.ok) {
+          appendsSucceeded += 1;
+        } else if (parsed.error) {
+          toolErrors.push({
+            iteration: iterations,
+            toolName: call.name,
+            toolCallId: call.id,
+            error: parsed.error,
+            args: call.args,
+          });
+        }
+      }
+
+      messages.push(
+        new ToolMessage({
+          content: rawResult,
+          tool_call_id: call.id ?? '',
+          name: call.name,
+        })
+      );
+    }
+  }
+
+  if (iterations >= maxIterations && lastIterationHadPendingCalls) {
+    hitIterationCap = true;
+    // Surface the last AIMessage text (if any) so callers can still log it.
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+      const m = messages[i];
+      if (m instanceof AIMessage) {
+        finalText = extractText(m);
+        break;
+      }
+    }
+  }
+
+  const silentReply = finalText.trim() === SILENT_REPLY_TOKEN;
+
+  return {
+    iterations,
+    appendsAttempted,
+    appendsSucceeded,
+    toolErrors,
+    silentReply,
+    hitIterationCap,
+    finalText,
+    messages,
+  };
+}

package/src/graphs/phases/memoryFlushPhase.ts

@@ -0,0 +1,209 @@
+/**
+ * Memory flush phase — trigger logic + reflection invocation.
+ *
+ * Ported from upstream'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.
+ *
+ * This module is INTENTIONALLY decoupled from the specific graph runtime —
+ * it exposes pure functions (`shouldFlushMemory`) plus a runner that takes
+ * the model as a parameter, so the same logic works from `createAgentNode`,
+ * `MultiAgentGraph`, or a future graph backend that wants to override
+ * flush behaviour.
+ *
+ * The agentic tool-execution loop (invoke → run tool_calls → feed results
+ * back → repeat until stop) lives in {@link ./flushLoop}. This module wires
+ * it up: build tools, resolve prompts, flip the phase, call the loop,
+ * shape the rich result.
+ */
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import {
+  DEFAULT_FLUSH_RESERVE_FLOOR_TOKENS,
+  DEFAULT_FLUSH_SOFT_THRESHOLD_TOKENS,
+  DEFAULT_MAX_FLUSH_ITERATIONS,
+  MEMORY_PHASE_FLUSHING,
+  MEMORY_PHASE_NORMAL,
+} from '@/memory/constants';
+import type { MemoryConfig } from '@/memory/types';
+import { buildMemoryTools } from '@/tools/memory';
+import { resolveFlushPrompts } from '@/prompts/memoryFlushPrompt';
+import {
+  bindToolsIfSupported,
+  runFlushLoop,
+  type FlushLoopResult,
+  type ToolErrorRecord,
+} from './flushLoop';
+
+export interface ShouldFlushInput {
+  currentTokens: number;
+  windowTokens: number;
+  reserveFloorTokens?: number;
+  softThresholdTokens?: number;
+}
+
+/**
+ * Pure trigger function: fires when the current context is within
+ * `softThreshold + reserveFloor` tokens of the model window. Matches
+ * upstream's formula.
+ */
+export function shouldFlushMemory(input: ShouldFlushInput): boolean {
+  if (
+    !Number.isFinite(input.currentTokens) ||
+    !Number.isFinite(input.windowTokens)
+  ) {
+    return false;
+  }
+  if (input.windowTokens <= 0) return false;
+  const reserve =
+    input.reserveFloorTokens ?? DEFAULT_FLUSH_RESERVE_FLOOR_TOKENS;
+  const soft = input.softThresholdTokens ?? DEFAULT_FLUSH_SOFT_THRESHOLD_TOKENS;
+  return input.currentTokens >= input.windowTokens - reserve - soft;
+}
+
+export interface RunFlushParams {
+  model: BaseChatModel;
+  memory: MemoryConfig;
+  /** A compact summary of the conversation — last N turns, not raw history. */
+  conversationSummary: string;
+  /**
+   * Accessor the graph runtime uses to expose the current phase to the
+   * append tool. The runner sets this to `memory_flushing` for the duration
+   * of the reflection turn and restores it on exit.
+   */
+  setPhase: (
+    phase: typeof MEMORY_PHASE_NORMAL | typeof MEMORY_PHASE_FLUSHING
+  ) => void;
+  /**
+   * @deprecated No longer used — the 8-path canonical-document model
+   * does not date-stamp files. Kept in the params shape for one release
+   * so host's callers don't break on the type signature.
+   */
+  timezone?: string;
+  /**
+   * @deprecated Same as `timezone` — unused in the canonical-document model.
+   */
+  nowMs?: number;
+  /** Override for the agentic-loop iteration cap. */
+  maxIterations?: number;
+  /**
+   * Optional per-iteration callback for structured debug logging.
+   * Caller is expected to demote this to debug once the rollout is stable.
+   */
+  onIteration?: (event: {
+    i: number;
+    toolCallCount: number;
+    toolNames: string[];
+  }) => void;
+}
+
+export interface RunFlushResult {
+  /** Did the flush actually run (false if disabled via config). */
+  ran: boolean;
+  /** Model.invoke() iterations actually performed. */
+  iterations?: number;
+  /** Total `memory_append` calls the model emitted. */
+  appendsAttempted?: number;
+  /** Subset that returned `{ ok: true }` from the backend. */
+  appendsSucceeded?: number;
+  /** Tool errors the model saw during the flush — surfaced for logging. */
+  toolErrors?: ToolErrorRecord[];
+  /** Final text reply equalled SILENT_REPLY_TOKEN (`NO_REPLY`). */
+  silentReply?: boolean;
+  /** Loop hit its iteration cap with tool_calls still pending. */
+  hitIterationCap?: boolean;
+  /** Final text reply from the last AIMessage. */
+  finalText?: string;
+  /** Error message if the flush threw. */
+  error?: string;
+}
+
+/**
+ * Run the reflection turn. The model is re-invoked with just the flush
+ * prompt + compact summary + the append tool unlocked. We intentionally
+ * drop the full history — the prompt tells the agent to write notes based
+ * on what it learned, not to continue the conversation.
+ *
+ * The loop keeps invoking the model until it stops emitting tool_calls,
+ * hits the iteration cap, or replies with {@link SILENT_REPLY_TOKEN}. Each
+ * `memory_append` tool_call is executed against the pgvector backend and
+ * the result (success path or error) is fed back as a ToolMessage so the
+ * model can self-correct (e.g. retry with a valid path).
+ */
+export async function runMemoryFlush(
+  params: RunFlushParams
+): Promise<RunFlushResult> {
+  const {
+    model,
+    memory,
+    conversationSummary,
+    setPhase,
+    maxIterations,
+    onIteration,
+  } = params;
+  if (memory.flush?.enabled === false) {
+    return { ran: false };
+  }
+
+  setPhase(MEMORY_PHASE_FLUSHING);
+  try {
+    const tools = buildMemoryTools({
+      ...memory,
+      readEnabled: false,
+      writeEnabled: true,
+      getPhase: () => MEMORY_PHASE_FLUSHING,
+    });
+
+    // Bind tools to the caller-provided model. If the model already came
+    // bound (some graph wrappers do), bindToolsIfSupported is a no-op.
+    const bound = bindToolsIfSupported(model, tools);
+
+    // Resolve flush prompts with the scope-aware rubric. For an
+    // isolated agent (no userId in scope), the user-tier paths are
+    // filtered out of the rubric so the LLM never sees them — it
+    // physically cannot route a write to `memory/user/*` because the
+    // prompt never lists those paths.
+    const { systemPrompt, prompt } = resolveFlushPrompts({
+      scope: memory.scope,
+    });
+    const initialMessages = [
+      new SystemMessage(systemPrompt),
+      new HumanMessage(
+        `${prompt}\n\nConversation context:\n\n${conversationSummary}`
+      ),
+    ];
+
+    const loop: FlushLoopResult = await runFlushLoop({
+      model: bound,
+      tools,
+      initialMessages,
+      maxIterations: maxIterations ?? DEFAULT_MAX_FLUSH_ITERATIONS,
+      onIteration: onIteration
+        ? (ev): void =>
+            onIteration({
+              i: ev.i,
+              toolCallCount: ev.toolCalls.length,
+              toolNames: ev.toolCalls.map((c) => c.name),
+            })
+        : undefined,
+    });
+
+    return {
+      ran: true,
+      iterations: loop.iterations,
+      appendsAttempted: loop.appendsAttempted,
+      appendsSucceeded: loop.appendsSucceeded,
+      toolErrors: loop.toolErrors,
+      silentReply: loop.silentReply,
+      hitIterationCap: loop.hitIterationCap,
+      finalText: loop.finalText,
+    };
+  } catch (err) {
+    return {
+      ran: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  } finally {
+    setPhase(MEMORY_PHASE_NORMAL);
+  }
+}

package/src/index.ts

@@ -5,7 +5,7 @@ export * from './splitStream';
 export * from './events';
 export * from './messages';
 
-/* Observability types re-exported for ranger consumption */
+/* Observability types re-exported for host consumption */
 export type {
   GuardrailTraceData,
   GuardrailOutcome,
@@ -25,6 +25,35 @@ export * from './tools/AskUser';
 export * from './tools/schema';
 export * from './tools/handlers';
 export * from './tools/search';
+export * from './tools/memory';
+
+/* Memory (storage + factory) */
+export * from './memory';
+
+/* Prompts */
+export { MEMORY_FLUSH_SYSTEM_PROMPT } from './prompts/memoryFlushPrompt';
+
+/* Phases */
+export {
+  shouldFlushMemory,
+  runMemoryFlush,
+} from './graphs/phases/memoryFlushPhase';
+export type {
+  RunFlushParams,
+  RunFlushResult,
+} from './graphs/phases/memoryFlushPhase';
+export {
+  runFlushLoop,
+  bindToolsIfSupported,
+  extractText as extractFlushText,
+  parseToolResult as parseFlushToolResult,
+} from './graphs/phases/flushLoop';
+export type {
+  FlushLoopParams,
+  FlushLoopResult,
+  ToolCallLike,
+  ToolErrorRecord,
+} from './graphs/phases/flushLoop';
 
 /* Schemas */
 export * from './schemas';

package/src/llm/bedrock/index.ts

@@ -172,14 +172,13 @@ export class IllumaBedrockConverse extends ChatBedrockConverse {
      * Some tools (e.g., MCP-sourced or dynamically created) may have empty or
      * missing descriptions. Patch them here to avoid Bedrock validation errors.
      */
-    if (
-      params.toolConfig?.tools &&
-      Array.isArray(params.toolConfig.tools)
-    ) {
+    if (params.toolConfig?.tools && Array.isArray(params.toolConfig.tools)) {
       for (const t of params.toolConfig.tools) {
         const spec = (t as { toolSpec?: { description?: string } }).toolSpec;
         if (spec && (!spec.description || spec.description === '')) {
-          spec.description = spec.description || `Tool: ${(spec as { name?: string }).name ?? 'unknown'}`;
+          spec.description =
+            spec.description ||
+            `Tool: ${(spec as { name?: string }).name ?? 'unknown'}`;
         }
       }
     }

package/src/memory/__tests__/citations.test.ts

@@ -0,0 +1,61 @@
+import {
+  decorateCitations,
+  resolveMemoryCitationsMode,
+  shouldIncludeCitations,
+  type CitationCandidate,
+} from '../citations';
+
+describe('resolveMemoryCitationsMode', () => {
+  it('accepts on/off/auto', () => {
+    expect(resolveMemoryCitationsMode('on')).toBe('on');
+    expect(resolveMemoryCitationsMode('off')).toBe('off');
+    expect(resolveMemoryCitationsMode('auto')).toBe('auto');
+  });
+  it('falls back to auto for anything else', () => {
+    expect(resolveMemoryCitationsMode(undefined)).toBe('auto');
+    expect(resolveMemoryCitationsMode('nonsense')).toBe('auto');
+  });
+});
+
+describe('shouldIncludeCitations', () => {
+  it('on → true, off → false, auto → true in direct chat', () => {
+    expect(shouldIncludeCitations('on')).toBe(true);
+    expect(shouldIncludeCitations('off')).toBe(false);
+    expect(shouldIncludeCitations('auto')).toBe(true);
+  });
+});
+
+describe('decorateCitations', () => {
+  it('strips citation when include=false', () => {
+    const hits = [
+      { path: 'memory/x.md', content: 'hello', citation: 'memory/x.md#L1' },
+    ];
+    const out = decorateCitations(hits, false);
+    expect(out[0].citation).toBeUndefined();
+  });
+
+  it('formats single-line citation as #L1', () => {
+    const hits: CitationCandidate[] = [
+      { path: 'memory/x.md', content: 'hello' },
+    ];
+    const out = decorateCitations(hits, true);
+    expect(out[0].citation).toBe('memory/x.md#L1');
+    expect(out[0].content).toContain('Source: memory/x.md#L1');
+  });
+
+  it('formats multi-line citation as #L1-LN', () => {
+    const hits: CitationCandidate[] = [
+      { path: 'memory/x.md', content: 'line1\nline2\nline3' },
+    ];
+    const out = decorateCitations(hits, true);
+    expect(out[0].citation).toBe('memory/x.md#L1-L3');
+  });
+
+  it('preserves caller-provided line range', () => {
+    const hits: CitationCandidate[] = [
+      { path: 'memory/x.md', content: 'ignored', startLine: 5, endLine: 12 },
+    ];
+    const out = decorateCitations(hits, true);
+    expect(out[0].citation).toBe('memory/x.md#L5-L12');
+  });
+});