@illuma-ai/agents 1.1.25 → 1.3.0

package/src/tools/memory/index.ts

@@ -0,0 +1,96 @@
+/**
+ * Public entry for the memory tool family.
+ *
+ * `buildMemoryTools` is the one function host calls. It returns an array
+ * of LangChain tools with scope captured in a closure — the LLM cannot
+ * override the `(agentId, userId)` pair through any tool argument.
+ *
+ * Phase 2: accepts independent `readEnabled` / `writeEnabled` flags that
+ * mirror host's existing `agent.memory_read_enabled` /
+ * `agent.memory_write_enabled` fields. Either flag can be set without the
+ * other: a read-only agent can consult memory without mutating it; a
+ * write-only agent can reflect without reading.
+ */
+import type { StructuredToolInterface } from '@langchain/core/tools';
+import type { MemoryConfig, MemoryPhase } from '@/memory/types';
+import { createMemorySearchTool } from './memorySearchTool';
+import { createMemoryGetTool } from './memoryGetTool';
+import { createMemoryAppendTool } from './memoryAppendTool';
+import type { MemoryToolBinding } from './shared';
+
+export * from './shared';
+export { createMemorySearchTool } from './memorySearchTool';
+export { createMemoryGetTool } from './memoryGetTool';
+export { createMemoryAppendTool } from './memoryAppendTool';
+
+export interface BuildMemoryToolsOptions extends MemoryConfig {
+  /**
+   * Attach `memory_search` + `memory_get`. Maps to
+   * `agent.memory_read_enabled` on the host Agent document.
+   */
+  readEnabled?: boolean;
+  /**
+   * Attach `memory_append` (still phase-gated to `memory_flushing`).
+   * Maps to `agent.memory_write_enabled` on the host Agent document.
+   */
+  writeEnabled?: boolean;
+  /**
+   * @deprecated — legacy Phase 1 flag. When set, equivalent to
+   * `{ readEnabled: true, writeEnabled: false }`. Kept so existing tests
+   * don't break during the Phase 1→2 transition. New callers should pass
+   * `readEnabled`/`writeEnabled` explicitly.
+   */
+  readOnly?: boolean;
+}
+
+export function buildMemoryTools(
+  options: BuildMemoryToolsOptions
+): StructuredToolInterface[] {
+  // Back-compat for the Phase 1 readOnly flag — maps to read-only mode.
+  let readEnabled = options.readEnabled;
+  let writeEnabled = options.writeEnabled;
+  if (options.readOnly) {
+    readEnabled = true;
+    writeEnabled = false;
+  }
+  // Default: if neither flag supplied, attach both (back-compat with the
+  // pre-Phase-2 single-flag caller).
+  if (readEnabled === undefined && writeEnabled === undefined) {
+    readEnabled = true;
+    writeEnabled = true;
+  }
+
+  const binding: MemoryToolBinding = {
+    backend: options.backend,
+    scope: options.scope,
+    maxInjectedChars: options.search?.maxInjectedChars,
+    searchOptions: {
+      mmr: options.search?.mmr,
+      temporalDecay: options.search?.temporalDecay,
+      citations: options.search?.citations,
+    },
+    recallTracker: options.recallTracker,
+  };
+
+  const tools: StructuredToolInterface[] = [];
+
+  if (readEnabled) {
+    tools.push(
+      createMemorySearchTool(binding) as unknown as StructuredToolInterface,
+      createMemoryGetTool(binding) as unknown as StructuredToolInterface
+    );
+  }
+
+  if (writeEnabled) {
+    const getPhase: () => MemoryPhase =
+      options.getPhase ?? ((): MemoryPhase => 'normal');
+    tools.push(
+      createMemoryAppendTool({
+        ...binding,
+        getPhase,
+      }) as unknown as StructuredToolInterface
+    );
+  }
+
+  return tools;
+}

package/src/tools/memory/memoryAppendTool.ts

@@ -0,0 +1,101 @@
+/**
+ * `memory_append` — the reflection-phase-only write tool.
+ *
+ * New (not present in upstream verbatim). Upstream enforces append-only via
+ * `wrapToolMemoryFlushAppendOnlyWrite`; we combine the tool and the phase
+ * gate in one place because the agents library has a simpler graph state.
+ *
+ * Behaviour:
+ * - Outside `memory_flushing` phase: returns an error object instead of
+ *   calling the backend. The LLM sees this and stops trying.
+ * - Inside `memory_flushing`: persists the note via {@link MemoryBackend.append}.
+ * - Hard-caps total appends per flush (protects against runaway writes).
+ */
+import { tool } from '@langchain/core/tools';
+import {
+  DEFAULT_MAX_APPENDS_PER_FLUSH,
+  MEMORY_APPEND_DESCRIPTION,
+  MEMORY_APPEND_TOOL_NAME,
+  MEMORY_PHASE_FLUSHING,
+} from '@/memory/constants';
+import type { MemoryPhase } from '@/memory/types';
+import {
+  MemoryAppendSchema,
+  toAppendInput,
+  type MemoryToolBinding,
+} from './shared';
+
+export interface MemoryAppendBinding extends MemoryToolBinding {
+  /**
+   * Reads the current phase at call-time. Required — without it the append
+   * tool rejects every call. Supplied by the graph runtime.
+   */
+  getPhase: () => MemoryPhase;
+  /** Hard cap on appends per flush phase. Default 20. */
+  maxAppendsPerFlush?: number;
+}
+
+interface AppendResult {
+  ok: boolean;
+  error?: string;
+  path?: string;
+}
+
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function createMemoryAppendTool(binding: MemoryAppendBinding) {
+  const maxAppends =
+    binding.maxAppendsPerFlush ?? DEFAULT_MAX_APPENDS_PER_FLUSH;
+  let appendsInCurrentFlush = 0;
+  let lastSeenPhase: MemoryPhase = 'normal';
+
+  return tool(
+    async (args): Promise<string> => {
+      const phase = binding.getPhase();
+
+      // Reset counter on entry to a new flush.
+      if (
+        phase === MEMORY_PHASE_FLUSHING &&
+        lastSeenPhase !== MEMORY_PHASE_FLUSHING
+      ) {
+        appendsInCurrentFlush = 0;
+      }
+      lastSeenPhase = phase;
+
+      if (phase !== MEMORY_PHASE_FLUSHING) {
+        const result: AppendResult = {
+          ok: false,
+          error:
+            'memory_append can only be called during the reflection (memory_flushing) phase',
+        };
+        return JSON.stringify(result);
+      }
+
+      if (appendsInCurrentFlush >= maxAppends) {
+        const result: AppendResult = {
+          ok: false,
+          error: `memory_append hit the per-flush cap of ${maxAppends} notes`,
+        };
+        return JSON.stringify(result);
+      }
+
+      try {
+        const input = toAppendInput(args);
+        await binding.backend.append(binding.scope, input);
+        appendsInCurrentFlush += 1;
+        const result: AppendResult = { ok: true, path: input.path };
+        return JSON.stringify(result);
+      } catch (err) {
+        const result: AppendResult = {
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+        return JSON.stringify(result);
+      }
+    },
+    {
+      name: MEMORY_APPEND_TOOL_NAME,
+      description: MEMORY_APPEND_DESCRIPTION,
+      schema: MemoryAppendSchema,
+    }
+  );
+}

package/src/tools/memory/memoryGetTool.ts

@@ -0,0 +1,53 @@
+/**
+ * `memory_get` — safe snippet read.
+ *
+ * Port of upstream `createMemoryGetTool` at
+ * `upstream reference`.
+ */
+import { tool } from '@langchain/core/tools';
+import {
+  MEMORY_GET_DESCRIPTION,
+  MEMORY_GET_TOOL_NAME,
+} from '@/memory/constants';
+import {
+  MemoryGetSchema,
+  type MemoryGetToolResult,
+  type MemoryToolBinding,
+} from './shared';
+
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function createMemoryGetTool(binding: MemoryToolBinding) {
+  return tool(
+    async (args): Promise<string> => {
+      try {
+        const result = await binding.backend.get(binding.scope, {
+          path: args.path,
+          from: args.from,
+          lines: args.lines,
+        });
+        if (!result) {
+          const payload: MemoryGetToolResult = { path: args.path, text: '' };
+          return JSON.stringify(payload);
+        }
+        const payload: MemoryGetToolResult = {
+          path: result.path,
+          text: result.text,
+        };
+        return JSON.stringify(payload);
+      } catch (err) {
+        const payload: MemoryGetToolResult = {
+          path: args.path,
+          text: '',
+          disabled: true,
+          error: err instanceof Error ? err.message : String(err),
+        };
+        return JSON.stringify(payload);
+      }
+    },
+    {
+      name: MEMORY_GET_TOOL_NAME,
+      description: MEMORY_GET_DESCRIPTION,
+      schema: MemoryGetSchema,
+    }
+  );
+}

package/src/tools/memory/memorySearchTool.ts

@@ -0,0 +1,80 @@
+/**
+ * `memory_search` — the mandatory-recall tool.
+ *
+ * Port of upstream `createMemorySearchTool` at
+ * `upstream reference`. The tool description
+ * is verbatim "Mandatory recall step..." from upstream — this is the load-
+ * bearing line that turns "the agent may recall" into "the agent will recall".
+ */
+import { tool } from '@langchain/core/tools';
+import {
+  MEMORY_SEARCH_DESCRIPTION,
+  MEMORY_SEARCH_TOOL_NAME,
+} from '@/memory/constants';
+import {
+  buildMemorySearchUnavailableResult,
+  clampResultsByInjectedChars,
+  MemorySearchSchema,
+  type MemorySearchToolResult,
+  type MemoryToolBinding,
+} from './shared';
+
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function createMemorySearchTool(binding: MemoryToolBinding) {
+  return tool(
+    async (args): Promise<string> => {
+      try {
+        const entries = await binding.backend.search(
+          binding.scope,
+          args.query,
+          {
+            maxResults: args.maxResults,
+            minScore: args.minScore,
+            mmr: binding.searchOptions?.mmr,
+            temporalDecay: binding.searchOptions?.temporalDecay,
+            citations: binding.searchOptions?.citations,
+          }
+        );
+        const clamped = clampResultsByInjectedChars(
+          entries,
+          binding.maxInjectedChars
+        );
+
+        // [phase2-recall-tracking] debug: fire-and-forget best-effort record
+        if (binding.recallTracker && clamped.length > 0) {
+          void binding.recallTracker
+            .record({
+              agentId: binding.scope.agentId,
+              query: args.query,
+              hits: clamped.map((e) => ({
+                id: e.id,
+                path: e.path,
+                score: e.score,
+              })),
+            })
+            .catch(() => undefined);
+        }
+
+        const payload: MemorySearchToolResult = {
+          results: clamped.map((entry) => ({
+            id: entry.id,
+            path: entry.path,
+            content: entry.content,
+            score: entry.score,
+            createdAt: entry.createdAt,
+            citation: entry.citation,
+          })),
+        };
+        return JSON.stringify(payload);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return JSON.stringify(buildMemorySearchUnavailableResult(message));
+      }
+    },
+    {
+      name: MEMORY_SEARCH_TOOL_NAME,
+      description: MEMORY_SEARCH_DESCRIPTION,
+      schema: MemorySearchSchema,
+    }
+  );
+}

package/src/tools/memory/shared.ts

@@ -0,0 +1,169 @@
+/**
+ * Shared Zod schemas + helpers for the memory tool family.
+ *
+ * The tool schemas deliberately do NOT expose `agent_id` or `user_id`. Scope
+ * is captured in a closure at tool construction time by {@link buildMemoryTools},
+ * so even a hallucinated tool call with extra fields cannot influence it.
+ */
+import { z } from 'zod';
+import {
+  DEFAULT_MAX_INJECTED_CHARS,
+  MEMORY_PATH_PREFIX,
+} from '@/memory/constants';
+import type {
+  MemoryAppendInput,
+  MemoryBackend,
+  MemoryEntry,
+  MemoryScope,
+} from '@/memory/types';
+
+export const MemorySearchSchema = z.object({
+  query: z.string().describe('Natural-language query to search memory for'),
+  maxResults: z
+    .number()
+    .int()
+    .min(1)
+    .max(50)
+    .optional()
+    .describe('Maximum number of results to return (default 10)'),
+  minScore: z
+    .number()
+    .min(0)
+    .max(1)
+    .optional()
+    .describe('Minimum hybrid score (0..1) below which results are dropped'),
+});
+
+export const MemoryGetSchema = z.object({
+  path: z
+    .string()
+    .describe(
+      'Memory path, e.g. "memory/decisions.md". Must start with "memory/"'
+    ),
+  from: z
+    .number()
+    .int()
+    .min(1)
+    .optional()
+    .describe('Starting line number (1-indexed)'),
+  lines: z
+    .number()
+    .int()
+    .min(1)
+    .optional()
+    .describe('Number of lines to read starting at `from`'),
+});
+
+export const MemoryAppendSchema = z.object({
+  path: z
+    .string()
+    .describe(
+      'Memory path to append to (e.g. "memory/decisions.md"). Must start with "memory/"'
+    ),
+  content: z
+    .string()
+    .min(1)
+    .describe(
+      "Note content in the agent's own voice. Markdown allowed. Each call appends an immutable entry."
+    ),
+});
+
+export type MemorySearchArgs = z.infer<typeof MemorySearchSchema>;
+export type MemoryGetArgs = z.infer<typeof MemoryGetSchema>;
+export type MemoryAppendArgs = z.infer<typeof MemoryAppendSchema>;
+
+/** Shape returned by `memory_search` — serialised as the tool result string. */
+export interface MemorySearchToolResult {
+  results: Array<
+    Pick<MemoryEntry, 'id' | 'path' | 'content' | 'score' | 'createdAt'> & {
+      citation?: string;
+    }
+  >;
+  disabled?: boolean;
+  unavailable?: boolean;
+  error?: string;
+  warning?: string;
+  action?: string;
+}
+
+/** Shape returned by `memory_get`. */
+export interface MemoryGetToolResult {
+  path: string;
+  text: string;
+  disabled?: boolean;
+  error?: string;
+}
+
+export function buildMemorySearchUnavailableResult(
+  error: string | undefined
+): MemorySearchToolResult {
+  const reason =
+    (error ?? 'memory search unavailable').trim() ||
+    'memory search unavailable';
+  const isQuota = /insufficient_quota|quota|429/i.test(reason);
+  return {
+    results: [],
+    disabled: true,
+    unavailable: true,
+    error: reason,
+    warning: isQuota
+      ? 'Memory search is unavailable because the embedding provider quota is exhausted.'
+      : 'Memory search is unavailable due to an embedding/provider error.',
+    action: isQuota
+      ? 'Top up or switch embedding provider, then retry memory_search.'
+      : 'Check embedding provider configuration and retry memory_search.',
+  };
+}
+
+/**
+ * Clamp a ranked result list to a total character budget.
+ * Ported from upstream `tools.citations.ts::clampResultsByInjectedChars`.
+ */
+export function clampResultsByInjectedChars<T extends { content: string }>(
+  results: T[],
+  maxInjectedChars: number = DEFAULT_MAX_INJECTED_CHARS
+): T[] {
+  const out: T[] = [];
+  let total = 0;
+  for (const result of results) {
+    const size = result.content.length ?? 0;
+    if (total + size > maxInjectedChars && out.length > 0) break;
+    out.push(result);
+    total += size;
+  }
+  return out;
+}
+
+export interface MemoryToolBinding {
+  backend: MemoryBackend;
+  scope: MemoryScope;
+  maxInjectedChars?: number;
+  /** Phase 2 — per-call search options propagated into backend.search. */
+  searchOptions?: {
+    mmr?: { enabled?: boolean; lambda?: number };
+    temporalDecay?: { enabled?: boolean; halfLifeDays?: number };
+    citations?: 'on' | 'off' | 'auto';
+  };
+  /** Phase 2 — optional best-effort recall recorder. */
+  recallTracker?: {
+    record(params: {
+      agentId: string;
+      query: string;
+      hits: Array<{ id: string; path: string; score: number }>;
+    }): Promise<void>;
+  };
+}
+
+export function assertAppendAllowed(path: string): void {
+  if (!path || !path.startsWith(MEMORY_PATH_PREFIX)) {
+    throw new Error(
+      `memory_append path must start with "${MEMORY_PATH_PREFIX}"`
+    );
+  }
+}
+
+/** Normalise an append call into the backend input shape. */
+export function toAppendInput(args: MemoryAppendArgs): MemoryAppendInput {
+  assertAppendAllowed(args.path);
+  return { path: args.path, content: args.content };
+}

package/src/tools/search/search.test.ts

@@ -12,7 +12,12 @@ describe('createSearchAPI', () => {
   const mockSerperResponse = {
     data: {
       organic: [
-        { position: 1, title: 'Test', link: 'https://example.com', snippet: 'test' },
+        {
+          position: 1,
+          title: 'Test',
+          link: 'https://example.com',
+          snippet: 'test',
+        },
       ],
       topStories: [],
       images: [],

package/src/types/graph.ts

@@ -56,6 +56,12 @@ export type AgentTransitionEvent = {
   destinationAgentName: string;
   edgeType: string; // 'handoff' | 'transfer' | 'sequence'
   timestamp: number;
+  /** When true, this event signals handoff completion (child → parent return) */
+  isCompletion?: boolean;
+  /** Duration of child agent execution in milliseconds (only on completion events) */
+  durationMs?: number;
+  /** Length of child agent result text in characters (only on completion events) */
+  resultLength?: number;
 };
 
 export type GraphNode = GraphNodeKeys | typeof START;
@@ -415,6 +421,13 @@ export type GraphEdge = {
    * Defaults to DEFAULT_HANDOFF_MAX_RESULT_CHARS (32768 chars, ~8192 tokens).
    */
   maxResultChars?: number;
+  /**
+   * For handoff edges: When true, the child agent receives the full parent
+   * conversation history plus the orchestrator's instructions appended.
+   * When false (default), the child only receives the orchestrator's scoped
+   * instructions — isolated from the parent conversation.
+   */
+  passthrough?: boolean;
   /**
    * Approval gate configuration for sequence edges.
    * When set, inserts an approval gate node between source and destination.
@@ -696,7 +709,7 @@ export interface AgentInputs {
   discoveredTools?: string[];
   /**
    * Optional callback for summarizing messages that were pruned from context.
-   * When provided, discarded messages are summarized by the caller (e.g., Ranger)
+   * When provided, discarded messages are summarized by the host caller
    * using a cheap LLM call, and the summary is prepended to the context.
    */
   summarizeCallback?: (
@@ -706,7 +719,7 @@ export interface AgentInputs {
    * Pre-existing summary text loaded from persistent storage (MongoDB/Redis).
    * When provided, this summary is injected into the initial message context
    * so the agent has prior conversation history even on new turns.
-   * Set by Ranger's SummaryStore when resuming a conversation.
+   * Set by the host's summary store when resuming a conversation.
    */
   persistedSummary?: string;
   /**
@@ -727,7 +740,7 @@ export interface AgentInputs {
    *   - file_search (RAG semantic search over embedded files)
    *   - content_tool read (by contentId for exact file retrieval)
    *
-   * Built by the orchestrator (e.g., Ranger) from message_file_map
+   * Built by the host orchestrator from message_file_map
    * and metadata.context_files across all conversation messages.
    */
   fileManifest?: FileManifestEntry[];