@illuma-ai/agents 1.1.28 → 1.3.1

package/src/tools/BrowserTools.ts

@@ -3,7 +3,7 @@ import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type * as _t from '@/types';
 
 /**
- * Browser tool names - keep in sync with ranger-browser extension
+ * Browser tool names - keep in sync with the browser extension
  * These tools execute locally in the browser extension, NOT on the server
  */
 export const EBrowserTools = {
@@ -26,7 +26,7 @@ export type BrowserToolName =
 
 /**
  * Callback function type for waiting on browser action results
- * This allows the server (Ranger) to provide a callback that waits for the extension
+ * This allows the host server to provide a callback that waits for the extension
  * to POST results back to the server before returning to the LLM.
  *
  * @param action - The browser action (click, type, navigate, etc.)
@@ -87,9 +87,7 @@ const BrowserClickSchema = z.object({
   label: z
     .string()
     .optional()
-    .describe(
-      'The fieldLabel or ariaLabel of the element, if available.'
-    ),
+    .describe('The fieldLabel or ariaLabel of the element, if available.'),
 });
 
 const BrowserTypeSchema = z.object({

package/src/tools/ToolNode.ts

@@ -188,9 +188,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     // Resolve the effective execution context for this agent.
     // Per-agent overrides take precedence — allows handoff agents to bypass HITL
     // while the primary agent retains interactive approval.
-    const effectiveContext = (
-      this.agentId && agentExecutionContextOverrides?.[this.agentId]
-    ) ?? executionContext;
+    const effectiveContext =
+      (this.agentId && agentExecutionContextOverrides?.[this.agentId]) ??
+      executionContext;
 
     // Scheduled executions bypass all approval checks — no user is present
     if (effectiveContext === ExecutionContext.SCHEDULED) {
@@ -205,9 +205,21 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       return false;
     }
 
-    // Graph-managed tools (handoff/transfer tools) bypass HITL approval —
-    // these are internal routing mechanisms, not user-facing tool executions
-    if (this.directToolNames?.has(toolName)) {
+    // Graph-managed routing tools (handoff/transfer) bypass HITL approval —
+    // these are internal routing mechanisms, not user-facing tool executions.
+    //
+    // NOTE: `directToolNames` is used for two purposes — (1) marking tools that
+    // are loaded as full instances and don't need on-demand ON_TOOL_EXECUTE loading,
+    // and (2) bypassing HITL. In event-driven mode ALL built-in tools (including
+    // `ask_user`) end up in directToolNames for reason (1), so we cannot use
+    // `directToolNames.has(toolName)` as the HITL-bypass test — it would let
+    // `ask_user` execute without ever firing interrupt(), defeating the whole tool.
+    // Instead, gate the bypass on the actual routing-tool name prefix.
+    if (
+      this.directToolNames?.has(toolName) &&
+      (toolName.startsWith(Constants.LC_TRANSFER_TO_) ||
+        toolName.startsWith(Constants.LC_HANDOFF_TO_))
+    ) {
       return false;
     }
 
@@ -240,10 +252,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
    * @param config - The runnable config for event dispatch
    * @returns The approval response from the human
    */
-  private requestApproval(
+  private async requestApproval(
     call: ToolCall,
     config: RunnableConfig
-  ): t.ToolApprovalResponse {
+  ): Promise<t.ToolApprovalResponse> {
     const approvalRequest: t.ToolApprovalRequest = {
       type: 'tool_approval_required',
       toolCallId: call.id ?? '',
@@ -253,9 +265,13 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       description: `Tool "${call.name}" wants to execute with the provided arguments.`,
     };
 
-    // Notify host before interrupting — allows SSE event emission and DB persistence.
-    // This is a fire-and-forget notification, NOT the approval mechanism.
-    safeDispatchCustomEvent(
+    // MUST await — interrupt() throws GraphInterrupt synchronously which unwinds
+    // the call stack. Any un-awaited dispatch Promise is abandoned before the
+    // host's ON_TOOL_APPROVAL_REQUIRED handler runs, so the MongoDB row never
+    // gets written and the subsequent approve-tool POST 404s with
+    // "No pending approval found". Awaiting guarantees the handler has persisted
+    // the request before we suspend the graph.
+    await safeDispatchCustomEvent(
       GraphEvents.ON_TOOL_APPROVAL_REQUIRED,
       approvalRequest,
       config
@@ -373,7 +389,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       if (
         this.requiresApproval(call.name, call.args as Record<string, unknown>)
       ) {
-        const approvalResponse = this.requestApproval(call, config);
+        const approvalResponse = await this.requestApproval(call, config);
         if (!approvalResponse.approved) {
           // Human denied the tool call - return a denial message
           return new ToolMessage({
@@ -825,7 +841,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       if (
         this.requiresApproval(call.name, call.args as Record<string, unknown>)
       ) {
-        const approvalResponse = this.requestApproval(call, config);
+        const approvalResponse = await this.requestApproval(call, config);
         if (!approvalResponse.approved) {
           denialMessages.push(
             new ToolMessage({
@@ -1152,6 +1168,127 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       }
     }
 
+    /**
+     * Dedupe handoffs targeting the same destination.
+     *
+     * Parent LLMs sometimes emit multiple parallel transfer_to_<agent> tool
+     * calls for the same child agent in one model tick (e.g. "send email 1"
+     * and "send email 2" both routed to the Productivity Assistant). LangGraph
+     * would otherwise create two parallel Sends into the same subgraph, which
+     * produces duplicate handoff entries in the UI and leaves extra
+     * tool_call_ids without a clean result when the single child run finishes.
+     *
+     * Merge same-destination handoffs into one Command whose update.messages
+     * carries every original ToolMessage — the primary one has its
+     * Instructions field rebuilt from the combined set, and the rest are kept
+     * verbatim so the parent message history has a ToolMessage for every
+     * tool_call_id (LangChain requires every AI tool_call to be resolved).
+     * The child's _extractTransferContext filters all transfer ToolMessages
+     * out of the child's view, so it only ever sees the merged instructions.
+     */
+    if (handoffCommands.length > 1) {
+      const byDestination = new Map<string, Command[]>();
+      for (const cmd of handoffCommands) {
+        const goto = cmd.goto;
+        const dest = typeof goto === 'string' ? goto : (goto as string[])[0];
+        const arr = byDestination.get(dest) ?? [];
+        arr.push(cmd);
+        byDestination.set(dest, arr);
+      }
+
+      const hasDuplicates = Array.from(byDestination.values()).some(
+        (arr) => arr.length > 1
+      );
+
+      if (hasDuplicates) {
+        const TRANSFER_INSTRUCTIONS_PATTERN =
+          /(?:Instructions?|Context):\s*(.+)/is;
+        const mergedHandoffs: Command[] = [];
+
+        for (const [dest, cmds] of byDestination) {
+          if (cmds.length === 1) {
+            mergedHandoffs.push(cmds[0]);
+            continue;
+          }
+
+          const allToolMessages: ToolMessage[] = [];
+          const allOtherMessages: BaseMessage[] = [];
+          for (const cmd of cmds) {
+            const upd = cmd.update as { messages?: BaseMessage[] } | undefined;
+            for (const m of upd?.messages ?? []) {
+              if (m.getType() === 'tool') {
+                allToolMessages.push(m as ToolMessage);
+              } else {
+                allOtherMessages.push(m);
+              }
+            }
+          }
+
+          if (allToolMessages.length === 0) {
+            mergedHandoffs.push(cmds[0]);
+            continue;
+          }
+
+          const primary = allToolMessages[0];
+          const primaryContent =
+            typeof primary.content === 'string'
+              ? primary.content
+              : JSON.stringify(primary.content);
+
+          const mergedInstructions: string[] = [];
+          for (const tm of allToolMessages) {
+            const c =
+              typeof tm.content === 'string'
+                ? tm.content
+                : JSON.stringify(tm.content);
+            const match = c.match(TRANSFER_INSTRUCTIONS_PATTERN);
+            if (match?.[1]) {
+              const instr = match[1].trim();
+              if (instr && !mergedInstructions.includes(instr)) {
+                mergedInstructions.push(instr);
+              }
+            }
+          }
+
+          let mergedPrimaryContent = primaryContent;
+          if (mergedInstructions.length > 1) {
+            const header = primaryContent
+              .replace(TRANSFER_INSTRUCTIONS_PATTERN, '')
+              .trimEnd();
+            const combinedInstr = mergedInstructions
+              .map((s, i) => `${i + 1}. ${s}`)
+              .join('\n');
+            mergedPrimaryContent =
+              `${header}\nInstructions: ${combinedInstr}`.trim();
+          }
+
+          const mergedPrimary = new ToolMessage({
+            content: mergedPrimaryContent,
+            tool_call_id: primary.tool_call_id,
+            name: primary.name,
+            additional_kwargs: { ...primary.additional_kwargs },
+          });
+
+          const mergedMessages: BaseMessage[] = [
+            mergedPrimary,
+            ...allToolMessages.slice(1),
+            ...allOtherMessages,
+          ];
+
+          mergedHandoffs.push(
+            new Command({
+              graph: Command.PARENT,
+              goto: dest,
+              update: { messages: mergedMessages },
+            })
+          );
+        }
+
+        handoffCommands.length = 0;
+        handoffCommands.push(...mergedHandoffs);
+      }
+    }
+
     /**
      * Handle handoff commands - convert to Send objects for parallel execution
      * when multiple handoffs are requested

package/src/tools/__tests__/ToolApproval.test.ts

@@ -86,7 +86,10 @@ function createTestGraph(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   compiled: any;
   notifications: t.ToolApprovalNotification[];
-  config: Partial<RunnableConfig> & { version: 'v1' | 'v2'; configurable: { thread_id: string } };
+  config: Partial<RunnableConfig> & {
+    version: 'v1' | 'v2';
+    configurable: { thread_id: string };
+  };
 } {
   const StateAnnotation = Annotation.Root({
     messages: Annotation<BaseMessage[]>({
@@ -145,7 +148,10 @@ function createTestGraph(
   const notifications: t.ToolApprovalNotification[] = [];
 
   // Collect notification events (data-only, no resolve/reject)
-  const config: Partial<RunnableConfig> & { version: 'v1' | 'v2'; configurable: { thread_id: string } } = {
+  const config: Partial<RunnableConfig> & {
+    version: 'v1' | 'v2';
+    configurable: { thread_id: string };
+  } = {
     version: 'v2',
     configurable: {
       thread_id: `test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
@@ -434,7 +440,12 @@ describe('HITL Tool Approval - Interrupt/Resume Flow', () => {
 
     // Resume with denial
     const result = await compiled.invoke(
-      new Command({ resume: { approved: false, feedback: 'Not now' } as t.ToolApprovalResponse }),
+      new Command({
+        resume: {
+          approved: false,
+          feedback: 'Not now',
+        } as t.ToolApprovalResponse,
+      }),
       config
     );
 
@@ -742,7 +753,10 @@ describe('HITL Tool Approval - Interrupt/Resume Flow', () => {
     const checkpointer = new MemorySaver();
     const compiled = workflow.compile({ checkpointer });
 
-    const config: Partial<RunnableConfig> & { version: 'v1' | 'v2'; configurable: { thread_id: string } } = {
+    const config: Partial<RunnableConfig> & {
+      version: 'v1' | 'v2';
+      configurable: { thread_id: string };
+    } = {
       version: 'v2',
       configurable: {
         thread_id: `test-multi-${Date.now()}`,
@@ -762,10 +776,7 @@ describe('HITL Tool Approval - Interrupt/Resume Flow', () => {
     };
 
     // First invoke: hits first interrupt
-    await compiled.invoke(
-      { messages: [new HumanMessage('Do both')] },
-      config
-    );
+    await compiled.invoke({ messages: [new HumanMessage('Do both')] }, config);
 
     // First interrupt notification received
     expect(notifications.length).toBeGreaterThanOrEqual(1);
@@ -784,7 +795,9 @@ describe('HITL Tool Approval - Interrupt/Resume Flow', () => {
 
     // Notifications fire on every re-execution (interrupt() replays the node),
     // so we check unique tool names rather than total count.
-    const uniqueTools = [...new Set(notifications.map((e) => e.toolName))].sort();
+    const uniqueTools = [
+      ...new Set(notifications.map((e) => e.toolName)),
+    ].sort();
     expect(uniqueTools).toEqual(['echo', 'send_email']);
   });
 });

package/src/tools/approval/__tests__/constants.test.ts

@@ -63,7 +63,7 @@ describe('HITL Approval Constants', () => {
   });
 
   describe('MCP_DELIMITER', () => {
-    it('should match Constants.mcp_delimiter from @ranger/data-provider', () => {
+    it('should match the host data-provider mcp_delimiter constant', () => {
       expect(MCP_DELIMITER).toBe('_mcp_');
     });
 

package/src/tools/approval/constants.ts

@@ -2,7 +2,7 @@
  * Shared HITL (Human-in-the-Loop) constants and enums.
  *
  * Single source of truth for approval-related values consumed by
- * the agents library, ranger backend, and browser extension.
+ * the agents library, host backend, and browser extension.
  *
  * @module approval/constants
  */
@@ -108,6 +108,6 @@ export enum ActionCategory {
  *
  * Example: `send_email_mcp_outlook` → tool = `send_email`, server = `outlook`
  *
- * Must match `Constants.mcp_delimiter` in `@ranger/data-provider`.
+ * Must match the host data-provider delimiter constant.
  */
 export const MCP_DELIMITER = '_mcp_';

package/src/tools/memory/__tests__/memoryTools.test.ts

@@ -0,0 +1,205 @@
+/**
+ * Unit tests for the memory tool family.
+ * Exercise the read path, the phase gate on append, and the isolation
+ * closure — all through the LangChain tool interface, against a mock backend.
+ */
+import { MockMemoryBackend } from '@/memory/__tests__/mockBackend';
+import { buildMemoryTools } from '../index';
+import {
+  MEMORY_APPEND_TOOL_NAME,
+  MEMORY_GET_TOOL_NAME,
+  MEMORY_PHASE_FLUSHING,
+  MEMORY_PHASE_NORMAL,
+  MEMORY_SEARCH_TOOL_NAME,
+} from '@/memory/constants';
+import type { MemoryPhase } from '@/memory/types';
+
+describe('buildMemoryTools', () => {
+  const scope = { agentId: 'sales', userId: 'alice' };
+
+  async function callTool(t: unknown, args: Record<string, unknown>) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (t as any).invoke(args) as Promise<string>;
+  }
+
+  it('exposes memory_search and memory_get in readOnly mode', () => {
+    const backend = new MockMemoryBackend();
+    const tools = buildMemoryTools({ backend, scope, readOnly: true });
+    const names = tools.map((t) => (t as { name: string }).name);
+    expect(names).toEqual([MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME]);
+  });
+
+  it('attaches memory_append when not readOnly', () => {
+    const backend = new MockMemoryBackend();
+    let phase: MemoryPhase = MEMORY_PHASE_NORMAL;
+    const tools = buildMemoryTools({
+      backend,
+      scope,
+      getPhase: () => phase,
+    });
+    const names = tools.map((t) => (t as { name: string }).name);
+    expect(names).toContain(MEMORY_APPEND_TOOL_NAME);
+  });
+
+  it('memory_search returns hits from the agent workspace only', async () => {
+    const backend = new MockMemoryBackend();
+    await backend.append(scope, {
+      path: 'memory/agent/playbook.md',
+      content: 'chose Postgres over Mongo for vector search',
+    });
+    await backend.append(
+      { agentId: 'support', userId: 'alice' },
+      { path: 'memory/agent/playbook.md', content: 'unrelated support note' }
+    );
+    const [search] = buildMemoryTools({ backend, scope, readOnly: true });
+    const result = JSON.parse(await callTool(search, { query: 'Postgres' }));
+    expect(result.results).toHaveLength(1);
+    expect(result.results[0].content).toContain('Postgres');
+  });
+
+  it('different user of same agent sees shared workspace', async () => {
+    const backend = new MockMemoryBackend();
+    // Alice writes in her session.
+    await backend.append(
+      { agentId: 'sales', userId: 'alice' },
+      {
+        path: 'memory/agent/playbook.md',
+        content: 'Alice learned pricing tiers',
+      }
+    );
+    // Bob searches in his session — same agent, shared workspace.
+    const [search] = buildMemoryTools({
+      backend,
+      scope: { agentId: 'sales', userId: 'bob' },
+      readOnly: true,
+    });
+    const result = JSON.parse(await callTool(search, { query: 'pricing' }));
+    expect(result.results).toHaveLength(1);
+    expect(result.results[0].content).toContain('pricing');
+  });
+
+  it('memory_append rejects outside memory_flushing phase', async () => {
+    const backend = new MockMemoryBackend();
+    const tools = buildMemoryTools({
+      backend,
+      scope,
+      getPhase: () => MEMORY_PHASE_NORMAL,
+    });
+    const append = tools.find(
+      (t) => (t as { name: string }).name === MEMORY_APPEND_TOOL_NAME
+    )!;
+    const result = JSON.parse(
+      await callTool(append, {
+        path: 'memory/agent/playbook.md',
+        content: 'hello',
+      })
+    );
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/reflection/);
+    expect(backend.allRows()).toHaveLength(0);
+  });
+
+  it('memory_append persists during memory_flushing phase', async () => {
+    const backend = new MockMemoryBackend();
+    const phase: MemoryPhase = MEMORY_PHASE_FLUSHING;
+    const tools = buildMemoryTools({
+      backend,
+      scope,
+      getPhase: () => phase,
+    });
+    const append = tools.find(
+      (t) => (t as { name: string }).name === MEMORY_APPEND_TOOL_NAME
+    )!;
+    const result = JSON.parse(
+      await callTool(append, {
+        path: 'memory/agent/playbook.md',
+        content: 'I decided to use pgvector.',
+      })
+    );
+    expect(result.ok).toBe(true);
+    expect(backend.allRows()).toHaveLength(1);
+    // Agent-tier row — scoping user_id is NULL, latest writer recorded
+    // as provenance via lastUserId.
+    expect(backend.allRows()[0].userId).toBeNull();
+    expect(backend.allRows()[0].lastUserId).toBe('alice');
+  });
+
+  it('memory_append merges multiple notes into one row per path', async () => {
+    const backend = new MockMemoryBackend();
+    const tools = buildMemoryTools({
+      backend,
+      scope,
+      getPhase: () => MEMORY_PHASE_FLUSHING,
+    });
+    const append = tools.find(
+      (t) => (t as { name: string }).name === MEMORY_APPEND_TOOL_NAME
+    )!;
+    await callTool(append, {
+      path: 'memory/agent/playbook.md',
+      content: 'first note',
+    });
+    await callTool(append, {
+      path: 'memory/agent/playbook.md',
+      content: 'second note',
+    });
+    const rows = backend.allRows();
+    expect(rows).toHaveLength(1);
+    expect(rows[0].content).toContain('first note');
+    expect(rows[0].content).toContain('second note');
+  });
+
+  it('memory_append rejects paths outside memory/', async () => {
+    const backend = new MockMemoryBackend();
+    const tools = buildMemoryTools({
+      backend,
+      scope,
+      getPhase: () => MEMORY_PHASE_FLUSHING,
+    });
+    const append = tools.find(
+      (t) => (t as { name: string }).name === MEMORY_APPEND_TOOL_NAME
+    )!;
+    const result = JSON.parse(
+      await callTool(append, {
+        path: 'secret.md',
+        content: 'escape',
+      })
+    );
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/memory\//);
+  });
+
+  it('memory_append rejects non-whitelisted paths even with memory/ prefix', async () => {
+    const backend = new MockMemoryBackend();
+    const tools = buildMemoryTools({
+      backend,
+      scope,
+      getPhase: () => MEMORY_PHASE_FLUSHING,
+    });
+    const append = tools.find(
+      (t) => (t as { name: string }).name === MEMORY_APPEND_TOOL_NAME
+    )!;
+    const result = JSON.parse(
+      await callTool(append, {
+        path: 'memory/random-notes.md',
+        content: 'escape',
+      })
+    );
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/whitelist/i);
+  });
+
+  it('tool args cannot inject agent_id into scope', async () => {
+    const backend = new MockMemoryBackend();
+    await backend.append(
+      { agentId: 'victim', userId: 'alice' },
+      { path: 'memory/agent/playbook.md', content: 'secret data' }
+    );
+    const [search] = buildMemoryTools({ backend, scope, readOnly: true });
+    // Try to pass a forged agent_id — Zod strips it, closure wins.
+    const result = JSON.parse(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      await callTool(search, { query: 'secret', agent_id: 'victim' } as any)
+    );
+    expect(result.results).toHaveLength(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;
+}