@illuma-ai/agents 1.1.28 → 1.3.1

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

@@ -421,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.
@@ -702,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?: (
@@ -712,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;
   /**
@@ -733,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[];

package/src/utils/__tests__/childAgentContext.test.ts

@@ -0,0 +1,217 @@
+/**
+ * Unit tests for child-agent context preparation.
+ *
+ * These strategies are the primary defense against schema confusion and
+ * Bedrock/VertexAI message-shape rejections, so their behavior must be
+ * locked down with fixtures that mirror real provider output shapes.
+ */
+import {
+  AIMessage,
+  HumanMessage,
+  SystemMessage,
+  ToolMessage,
+} from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import {
+  HANDOFF_TAIL_CONTEXT_PREFIX,
+  buildIsolatedChildPrompt,
+  prepareHandoffMessages,
+  prepareIsolatedChildMessages,
+} from '../childAgentContext';
+
+describe('buildIsolatedChildPrompt', () => {
+  it('wraps upstream text in the prior-step / your-task sections', () => {
+    const out = buildIsolatedChildPrompt('RESEARCH FINDINGS');
+    expect(out).toContain('## Prior step output');
+    expect(out).toContain('RESEARCH FINDINGS');
+    expect(out).toContain('## Your task');
+    expect(out).toMatch(/You MUST now/);
+  });
+
+  it('instructs the model to call tools directly without asking for clarification', () => {
+    const out = buildIsolatedChildPrompt('x');
+    expect(out).toMatch(/call it directly/);
+    expect(out).toMatch(/do not ask for clarification/);
+  });
+});
+
+describe('prepareHandoffMessages', () => {
+  it('returns an empty array unchanged', () => {
+    expect(prepareHandoffMessages([])).toEqual([]);
+  });
+
+  it('preserves system and human messages verbatim', () => {
+    const msgs: BaseMessage[] = [
+      new SystemMessage('sys'),
+      new HumanMessage('hello'),
+    ];
+    const out = prepareHandoffMessages(msgs);
+    expect(out).toHaveLength(2);
+    expect(out[0].getType()).toBe('system');
+    expect(out[1].getType()).toBe('human');
+  });
+
+  it('drops orphaned tool_use blocks (handoff tool has no matching result)', () => {
+    const ai = new AIMessage({
+      content: 'transferring',
+      tool_calls: [{ name: 'handoff_to_writer', args: {}, id: 'call_1' }],
+    });
+    const out = prepareHandoffMessages([new HumanMessage('go'), ai]);
+    // The assistant tail becomes a HumanMessage with the context prefix
+    // because the orphaned tool_use was stripped, leaving only text.
+    expect(out).toHaveLength(2);
+    expect(out[1].getType()).toBe('human');
+    expect(out[1].content).toContain('transferring');
+    expect(out[1].content).toContain(HANDOFF_TAIL_CONTEXT_PREFIX);
+  });
+
+  it('compacts paired tool_use/tool_result into a text summary', () => {
+    const ai = new AIMessage({
+      content: '',
+      tool_calls: [{ name: 'search', args: { q: 'x' }, id: 'call_a' }],
+    });
+    const toolResult = new ToolMessage({
+      content: 'hit: 42',
+      tool_call_id: 'call_a',
+    });
+    const out = prepareHandoffMessages([
+      new HumanMessage('find x'),
+      ai,
+      toolResult,
+      new HumanMessage('what did you find?'),
+    ]);
+    // The paired tool_use+result should have become a text summary on the
+    // rewritten AI message; the original ToolMessage should be gone.
+    expect(out.some((m) => m.getType() === 'tool')).toBe(false);
+    const rewrittenAI = out.find((m) => m.getType() === 'ai');
+    expect(rewrittenAI).toBeDefined();
+    expect(String(rewrittenAI?.content)).toContain('[Tool "search"');
+    expect(String(rewrittenAI?.content)).toContain('hit: 42');
+  });
+
+  it('truncates long tool_result content at 500 chars in the summary', () => {
+    const long = 'x'.repeat(1200);
+    const ai = new AIMessage({
+      content: '',
+      tool_calls: [{ name: 'dump', args: {}, id: 'call_big' }],
+    });
+    const tool = new ToolMessage({ content: long, tool_call_id: 'call_big' });
+    const out = prepareHandoffMessages([new HumanMessage('hi'), ai, tool]);
+    // After the paired compaction the tail is an AIMessage with no text, so
+    // it gets dropped (empty) — find the one that carries the summary by
+    // scanning for the "[Tool" marker in any message.
+    const blob = out.map((m) => String(m.content)).join(' ');
+    expect(blob).toContain('[Tool "dump"');
+    // The truncated slice is 500 chars of x, not the full 1200.
+    const match = blob.match(/x+/);
+    expect(match).toBeTruthy();
+    expect((match?.[0].length ?? 0) <= 500).toBe(true);
+  });
+
+  it('ensures the tail message is a HumanMessage by rewriting a trailing AI', () => {
+    const msgs: BaseMessage[] = [
+      new HumanMessage('question'),
+      new AIMessage('plain text answer'),
+    ];
+    const out = prepareHandoffMessages(msgs);
+    expect(out[out.length - 1].getType()).toBe('human');
+    expect(out[out.length - 1].content).toBe(
+      `${HANDOFF_TAIL_CONTEXT_PREFIX}plain text answer`
+    );
+  });
+
+  it('drops a trailing empty AIMessage instead of creating an empty human', () => {
+    const msgs: BaseMessage[] = [
+      new HumanMessage('q'),
+      new AIMessage(''), // empty, nothing to carry forward
+    ];
+    const out = prepareHandoffMessages(msgs);
+    expect(out).toHaveLength(1);
+    expect(out[0].getType()).toBe('human');
+  });
+});
+
+describe('prepareIsolatedChildMessages', () => {
+  it('returns empty input unchanged', () => {
+    expect(prepareIsolatedChildMessages([])).toEqual([]);
+  });
+
+  it('keeps only the first human message and a synthetic directive', () => {
+    const msgs: BaseMessage[] = [
+      new HumanMessage('original request'),
+      new AIMessage('upstream produced this result'),
+    ];
+    const out = prepareIsolatedChildMessages(msgs);
+    expect(out).toHaveLength(2);
+    expect(out[0].getType()).toBe('human');
+    expect(out[0].content).toBe('original request');
+    expect(out[1].getType()).toBe('human');
+    expect(String(out[1].content)).toContain('upstream produced this result');
+    expect(String(out[1].content)).toContain('## Your task');
+  });
+
+  it('discards upstream tool_use/tool_result blocks entirely', () => {
+    const aiWithTool = new AIMessage({
+      content: 'working',
+      tool_calls: [{ name: 'search', args: {}, id: 'c1' }],
+    });
+    const toolResult = new ToolMessage({
+      content: 'search result',
+      tool_call_id: 'c1',
+    });
+    const aiFinal = new AIMessage('final summary text');
+    const out = prepareIsolatedChildMessages([
+      new HumanMessage('user ask'),
+      aiWithTool,
+      toolResult,
+      aiFinal,
+    ]);
+    // Must not contain any ToolMessage or upstream tool_calls.
+    expect(out.some((m) => m.getType() === 'tool')).toBe(false);
+    // The synthetic directive should reference only the final text output.
+    const directive = String(out[1].content);
+    expect(directive).toContain('final summary text');
+    expect(directive).not.toContain('search result');
+  });
+
+  it('picks the most recent non-empty AI text output', () => {
+    const msgs: BaseMessage[] = [
+      new HumanMessage('req'),
+      new AIMessage('older text'),
+      new AIMessage(''),
+      new AIMessage('newer text'),
+    ];
+    const out = prepareIsolatedChildMessages(msgs);
+    expect(String(out[1].content)).toContain('newer text');
+    expect(String(out[1].content)).not.toContain('older text');
+  });
+
+  it('handles AI content in Anthropic array-of-blocks shape', () => {
+    const ai = new AIMessage({
+      content: [
+        { type: 'tool_use', name: 'x', input: {}, id: 'c1' },
+        { type: 'text', text: 'block text result' },
+      ] as unknown as string, // the SDK types are strict, cast for fixture
+    });
+    const out = prepareIsolatedChildMessages([new HumanMessage('q'), ai]);
+    expect(out).toHaveLength(2);
+    expect(String(out[1].content)).toContain('block text result');
+  });
+
+  it('falls back to raw messages if no human and no upstream text exist', () => {
+    const msgs: BaseMessage[] = [new SystemMessage('just system')];
+    const out = prepareIsolatedChildMessages(msgs);
+    expect(out).toBe(msgs);
+  });
+
+  it('returns just the user message when upstream has no text content', () => {
+    const msgs: BaseMessage[] = [
+      new HumanMessage('only user'),
+      new AIMessage(''),
+    ];
+    const out = prepareIsolatedChildMessages(msgs);
+    expect(out).toHaveLength(1);
+    expect(out[0].getType()).toBe('human');
+    expect(out[0].content).toBe('only user');
+  });
+});