melchizedek-agents 0.18.0 → 0.19.0

package/dist/lib/tools/examples.js

@@ -0,0 +1,62 @@
+/**
+ * lib/tools/examples.ts — an agent's `examples:` as an instruction block
+ * (ADR 0059, ADR 0062).
+ *
+ * WHY this file exists:
+ *   A YAML agent's `examples:` lists exchanges the model should imitate. ADK's
+ *   ExampleTool wrote them into the system instruction of each request as a
+ *   few-shot block, and the native runtime needs the same block without ADK.
+ *   Writing into the instruction is what an InstructionTool does
+ *   (lib/tools/tool.ts), so the examples are one: it declares no function,
+ *   is never called, and adds the block, word for word as ExampleTool
+ *   formatted it, before each request. The ADK runtime receives it through
+ *   toAdkInstructionTool (lib/tools/adkTool.ts), which appends it where
+ *   ExampleTool did.
+ *
+ *   As with ExampleTool, the block is added only when the message that
+ *   started the run begins with text. YAML examples are text alone, so the
+ *   function-call renderings ExampleTool also had never apply.
+ *
+ * The examples are the agent author's prompt text, not the user's words.
+ * A LEAF: nothing in its import graph names @google/*.
+ */
+/** The name ADK's ExampleTool carried, which the instruction block keeps. */
+export const EXAMPLES_TOOL_NAME = 'example_tool';
+// ExampleTool's strings (ADK's examples/example_util.js), kept word for word.
+const EXAMPLES_INTRO = '<EXAMPLES>\nBegin few-shot\nThe following are examples of user queries and model responses using the available tools.\n\n';
+const EXAMPLES_END = 'End few-shot\n<EXAMPLES>';
+const EXAMPLE_END = 'End example\n\n';
+const USER_PREFIX = '[user]\n';
+const MODEL_PREFIX = '[model]\n';
+/**
+ * The few-shot block for `examples`, as ExampleTool rendered text-only
+ * examples: each numbered, the user's text then the model's, each line
+ * ending in a newline. An empty input or output keeps its role line and
+ * adds no text, as ExampleTool did.
+ */
+export function examplesInstruction(examples) {
+    let body = '';
+    examples.forEach((example, i) => {
+        body += `EXAMPLE ${i + 1}:\nBegin example\n${USER_PREFIX}`;
+        body += `${example.input ? example.input : ''}\n`;
+        body += MODEL_PREFIX;
+        if (example.output)
+            body += `${example.output}\n`;
+        body += EXAMPLE_END;
+    });
+    return `${EXAMPLES_INTRO}${body}${EXAMPLES_END}`;
+}
+/**
+ * An agent's examples as an InstructionTool, or undefined when it has none.
+ * It adds the block when the run's first message begins with text, as
+ * ExampleTool did, and nothing otherwise.
+ */
+export function examplesInstructionTool(examples) {
+    if (!examples?.length)
+        return undefined;
+    const text = examplesInstruction(examples);
+    return {
+        name: EXAMPLES_TOOL_NAME,
+        instruction: async (ctx) => (ctx.userContent?.parts?.[0]?.text ? text : undefined),
+    };
+}

package/dist/lib/tools/generateImageTool.d.ts

@@ -1,16 +1,25 @@
 /**
- * generateImageTool — native ADK FunctionTool for real image generation.
+ * generateImageTool — a tool contract for real image generation.
  *
- * WHY a FunctionTool instead of an AgentTool subagent:
+ * WHY a function tool instead of an AgentTool subagent:
  *   AgentTool converts all subagent output to a text function-response before
  *   returning it to the orchestrator. Binary inlineData (the base64 image bytes
  *   from an image-generation model) is therefore lost in transit.
  *
- *   A FunctionTool runs arbitrary TypeScript: we call @google/genai directly,
+ *   A function tool runs arbitrary TypeScript: we call @google/genai directly,
  *   receive the raw response including inlineData, write the file to disk, and
  *   return a plain-text confirmation with the saved file path. The orchestrator
  *   sees the path and relays it to the user.
+ *
+ * The contract is an own Tool (lib/tools/tool.ts); `generateImageTool` is the
+ * FunctionTool the ADK runtime runs, made from it by toFunctionTool.
  */
-import { FunctionTool } from '@google/adk';
-import { type Schema } from '@google/genai';
-export declare const generateImageTool: FunctionTool<Schema>;
+import { z } from 'zod';
+export declare const generateImageContract: import("./toolContract.ts").DefinedTool<z.ZodObject<{
+    prompt: z.ZodString;
+    style: z.ZodOptional<z.ZodString>;
+    aspect_ratio: z.ZodOptional<z.ZodString>;
+    color_palette: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, string>;
+/** ADK surface, ready for the registry. */
+export declare const generateImageTool: import("@google/adk").FunctionTool<undefined>;

package/dist/lib/tools/generateImageTool.js

@@ -1,50 +1,38 @@
 /**
- * generateImageTool — native ADK FunctionTool for real image generation.
+ * generateImageTool — a tool contract for real image generation.
  *
- * WHY a FunctionTool instead of an AgentTool subagent:
+ * WHY a function tool instead of an AgentTool subagent:
  *   AgentTool converts all subagent output to a text function-response before
  *   returning it to the orchestrator. Binary inlineData (the base64 image bytes
  *   from an image-generation model) is therefore lost in transit.
  *
- *   A FunctionTool runs arbitrary TypeScript: we call @google/genai directly,
+ *   A function tool runs arbitrary TypeScript: we call @google/genai directly,
  *   receive the raw response including inlineData, write the file to disk, and
  *   return a plain-text confirmation with the saved file path. The orchestrator
  *   sees the path and relays it to the user.
+ *
+ * The contract is an own Tool (lib/tools/tool.ts); `generateImageTool` is the
+ * FunctionTool the ADK runtime runs, made from it by toFunctionTool.
  */
-import { FunctionTool } from '@google/adk';
 import { GoogleGenAI } from '@google/genai';
 import { writeFileSync, mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { z } from 'zod';
+import { toFunctionTool } from './adkTool.js';
+import { defineTool } from './toolContract.js';
 const IMAGE_MODEL = 'gemini-3.1-flash-image-preview';
-export const generateImageTool = new FunctionTool({
+export const generateImageContract = defineTool({
     name: 'generate_image',
     description: 'Generates a real image from a structured payload and saves it to the outputs/ directory. ' +
         'Returns the saved file path. Call this only after the user has approved the image payload.',
-    parameters: {
-        type: 'OBJECT',
-        properties: {
-            prompt: {
-                type: 'STRING',
-                description: 'The full image prompt describing the scene and subject.',
-            },
-            style: {
-                type: 'STRING',
-                description: 'Visual style (e.g. "Ansel Adams", "impressionist", "photorealistic").',
-            },
-            aspect_ratio: {
-                type: 'STRING',
-                description: 'Desired aspect ratio (e.g. "3:2", "16:9", "1:1").',
-            },
-            color_palette: {
-                type: 'STRING',
-                description: 'Color palette guidance (e.g. "monochromatic", "warm tones", "vivid").',
-            },
-        },
-        required: ['prompt'],
-    },
-    execute: async (input) => {
+    schema: z.object({
+        prompt: z.string().describe('The full image prompt describing the scene and subject.'),
+        style: z.string().optional().describe('Visual style (e.g. "Ansel Adams", "impressionist", "photorealistic").'),
+        aspect_ratio: z.string().optional().describe('Desired aspect ratio (e.g. "3:2", "16:9", "1:1").'),
+        color_palette: z.string().optional().describe('Color palette guidance (e.g. "monochromatic", "warm tones", "vivid").'),
+    }),
+    execute: async ({ prompt, style, aspect_ratio, color_palette }) => {
         console.log("[ImageTool] Starting image generation execution...");
-        const { prompt, style, aspect_ratio, color_palette } = input;
         const apiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_GENAI_API_KEY;
         if (!apiKey) {
             const err = new Error('Gemini API Key is not configured (neither GEMINI_API_KEY nor GOOGLE_GENAI_API_KEY was found in environment).');
@@ -117,3 +105,5 @@ export const generateImageTool = new FunctionTool({
         }
     },
 });
+/** ADK surface, ready for the registry. */
+export const generateImageTool = toFunctionTool(generateImageContract);

package/dist/lib/tools/inspectImageTool.d.ts

@@ -1,10 +1,10 @@
 /**
- * inspectImageTool — native ADK FunctionTool for BLIND visual inventory.
+ * inspectImageTool — a tool contract for BLIND visual inventory.
  *
- * WHY a FunctionTool instead of an AgentTool subagent:
+ * WHY a function tool instead of an AgentTool subagent:
  *   Same constraint as generateImageTool in reverse — AgentTool converts all
  *   traffic to text, so image bytes can't ride into a subagent's context.
- *   A FunctionTool reads the saved file directly and calls the vision model
+ *   A function tool reads the saved file directly and calls the vision model
  *   itself.
  *
  * WHY the inventory prompt is hard-coded here and takes ONLY a file path:
@@ -16,6 +16,9 @@
  *   system, not by good intentions. Judgment happens downstream in the
  *   SpecAuditor subagent, which sees spec + inventory but never the image.
  */
-import { FunctionTool } from '@google/adk';
-import { type Schema } from '@google/genai';
-export declare const inspectImageTool: FunctionTool<Schema>;
+import { z } from 'zod';
+export declare const inspectImageContract: import("./toolContract.ts").DefinedTool<z.ZodObject<{
+    image_path: z.ZodString;
+}, z.core.$strip>, string>;
+/** ADK surface, ready for the registry. */
+export declare const inspectImageTool: import("@google/adk").FunctionTool<undefined>;

package/dist/lib/tools/inspectImageTool.js

@@ -1,10 +1,10 @@
 /**
- * inspectImageTool — native ADK FunctionTool for BLIND visual inventory.
+ * inspectImageTool — a tool contract for BLIND visual inventory.
  *
- * WHY a FunctionTool instead of an AgentTool subagent:
+ * WHY a function tool instead of an AgentTool subagent:
  *   Same constraint as generateImageTool in reverse — AgentTool converts all
  *   traffic to text, so image bytes can't ride into a subagent's context.
- *   A FunctionTool reads the saved file directly and calls the vision model
+ *   A function tool reads the saved file directly and calls the vision model
  *   itself.
  *
  * WHY the inventory prompt is hard-coded here and takes ONLY a file path:
@@ -16,10 +16,12 @@
  *   system, not by good intentions. Judgment happens downstream in the
  *   SpecAuditor subagent, which sees spec + inventory but never the image.
  */
-import { FunctionTool } from '@google/adk';
 import { GoogleGenAI } from '@google/genai';
 import { readFileSync } from 'node:fs';
 import { resolve, extname, sep } from 'node:path';
+import { z } from 'zod';
+import { toFunctionTool } from './adkTool.js';
+import { defineTool } from './toolContract.js';
 const VISION_MODEL = 'gemini-3.8-flash';
 const INVENTORY_PROTOCOL = `You are a blind visual inventory agent. You know NOTHING about what this image was supposed to be, who requested it, or why. Enumerate ONLY what is actually present:
 
@@ -36,23 +38,15 @@ RULES:
 - ZERO guesses about intent or purpose.
 - If something is genuinely ambiguous, write "uncertain:" and describe what is visible.
 Return a plain, factual, numbered inventory.`;
-export const inspectImageTool = new FunctionTool({
+export const inspectImageContract = defineTool({
     name: 'inspect_image',
     description: 'Performs a BLIND visual inventory of a previously saved image (subjects with exact counts, ' +
         'composition, light, palette, medium cues, artifacts). Pass ONLY the file path returned by ' +
         'generate_image — never describe the expected content, or the inventory will be primed.',
-    parameters: {
-        type: 'OBJECT',
-        properties: {
-            image_path: {
-                type: 'STRING',
-                description: 'Path to the saved image, e.g. "outputs/image_1234.png".',
-            },
-        },
-        required: ['image_path'],
-    },
-    execute: async (input) => {
-        const { image_path } = input;
+    schema: z.object({
+        image_path: z.string().describe('Path to the saved image, e.g. "outputs/image_1234.png".'),
+    }),
+    execute: async ({ image_path }) => {
         console.log(`[InspectTool] Blind inventory requested for: ${image_path}`);
         // Confine reads to the outputs/ directory — this tool inventories
         // generated artifacts, not the filesystem. OUTPUTS_DIR env overrides
@@ -95,3 +89,5 @@ export const inspectImageTool = new FunctionTool({
         return `BLIND INVENTORY of ${image_path}:\n${text}`;
     },
 });
+/** ADK surface, ready for the registry. */
+export const inspectImageTool = toFunctionTool(inspectImageContract);

package/dist/lib/tools/mcpToolFactory.d.ts

@@ -1,5 +1,23 @@
-import { FunctionTool } from '@google/adk';
+/**
+ * lib/tools/mcpToolFactory.ts — a remote MCP server's tools, as the
+ * engine's own Tools (lib/tools/tool.ts, ADR 0062).
+ *
+ * An agent's `mcp_server_url:` connects here over SSE; every tool the
+ * server lists becomes an own Tool whose declaration is the server's
+ * description (bounded) and input schema, and whose execute calls the
+ * server and returns its text (bounded). loadMcpTools returns them for the
+ * native runtime; createMcpTools hands the ADK runtime the FunctionTool
+ * toFunctionTool (lib/tools/adkTool.ts) makes of each, so both runtimes
+ * declare the same parameters and run the same call.
+ *
+ * The server is an untrusted tool vendor (ADR 0041): its URL passes the
+ * SSRF guard, a credential goes only to its exact host, and its
+ * descriptions and results are cut to a bound.
+ */
+import type { FunctionTool } from '@google/adk';
+import type { ToolDeclaration } from '../models/contract.ts';
 import type { RedirectPolicy } from '../net/redirects.ts';
+import type { Tool } from './tool.ts';
 export declare function assertSafeMcpUrl(raw: string, env?: NodeJS.ProcessEnv): Promise<URL>;
 export declare function mcpAuthHeaders(url: URL, env?: NodeJS.ProcessEnv): Record<string, string>;
 /**
@@ -19,6 +37,7 @@ export declare const mcpFetch: (input: string | URL | Request, init?: RequestIni
  * so a server cannot flood the context (or the bill) with either.
  */
 export declare const MAX_MCP_DESCRIPTION_CHARS = 1000;
+/** Every tool's shared result limit (lib/tools/tool.ts). */
 export declare const MAX_MCP_RESULT_CHARS = 20000;
 /**
  * Close every open MCP connection. A connection otherwise lives as long as
@@ -27,4 +46,26 @@ export declare const MAX_MCP_RESULT_CHARS = 20000;
  * stops cleanly, or a test, calls this.
  */
 export declare function closeMcpConnections(): Promise<void>;
+/**
+ * The parameters an MCP tool declares: the server's input schema, each
+ * top-level property given a type (string when the server names none) and a
+ * description, in the contract's lowercase dialect. They pass through
+ * Gemini's dialect first (toGeminiSchema), so the declaration is exactly
+ * what the ADK runtime's FunctionTool declares: `default`, `propertyNames`,
+ * `$schema` and a boolean `additionalProperties` are left out on both.
+ */
+export declare function mcpToolParameters(inputSchema: {
+    properties?: Record<string, unknown>;
+    required?: string[];
+} | undefined): ToolDeclaration['parameters'];
+/**
+ * The tools a remote MCP server offers, as own Tools, or none when the
+ * server cannot be reached or refuses (logged, never thrown). The
+ * connection stays open for the tools' calls; closeMcpConnections ends it.
+ */
+export declare function loadMcpTools(mcpServerUrl: string): Promise<Tool[]>;
+/**
+ * The server's tools as the ADK runtime runs them: the FunctionTool
+ * toFunctionTool makes of each own Tool, carrying it for toolOf().
+ */
 export declare function createMcpTools(mcpServerUrl: string): Promise<FunctionTool[]>;

package/dist/lib/tools/mcpToolFactory.js

@@ -1,8 +1,11 @@
-import { FunctionTool } from '@google/adk';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { toContractJsonSchema } from '../models/schemaNormalize.js';
 import { checkHost } from '../net/addressGuard.js';
 import { fetchWithRedirectPolicy } from '../net/redirects.js';
+import { toFunctionTool } from './adkTool.js';
+import { MAX_RESULT_CHARS } from './tool.js';
+import { toGeminiSchema } from './toolContract.js';
 // Security (SSRF): mcp_server_url can arrive from a registry-stored syndicate
 // config. Only http(s), and the host must pass lib/net/addressGuard.ts (the
 // same guard web_extract uses): local names and non-public addresses —
@@ -87,7 +90,8 @@ export const mcpFetch = (input, init) => fetchWithRedirectPolicy(input, init, MC
  * so a server cannot flood the context (or the bill) with either.
  */
 export const MAX_MCP_DESCRIPTION_CHARS = 1_000;
-export const MAX_MCP_RESULT_CHARS = 20_000;
+/** Every tool's shared result limit (lib/tools/tool.ts). */
+export const MAX_MCP_RESULT_CHARS = MAX_RESULT_CHARS;
 const bounded = (text, max, what) => text.length <= max ? text : `${text.slice(0, max)}… [${what} cut at ${max} characters]`;
 /** Every MCP connection opened and still in use, so a shutdown can close them. */
 const openTransports = new Set();
@@ -102,7 +106,28 @@ export async function closeMcpConnections() {
     openTransports.clear();
     await Promise.all(all.map((t) => t.close().catch(() => { })));
 }
-export async function createMcpTools(mcpServerUrl) {
+/**
+ * The parameters an MCP tool declares: the server's input schema, each
+ * top-level property given a type (string when the server names none) and a
+ * description, in the contract's lowercase dialect. They pass through
+ * Gemini's dialect first (toGeminiSchema), so the declaration is exactly
+ * what the ADK runtime's FunctionTool declares: `default`, `propertyNames`,
+ * `$schema` and a boolean `additionalProperties` are left out on both.
+ */
+export function mcpToolParameters(inputSchema) {
+    const properties = {};
+    for (const [key, prop] of Object.entries(inputSchema?.properties ?? {})) {
+        properties[key] = { ...prop, type: prop?.type ?? 'string', description: prop?.description || '' };
+    }
+    const required = Array.isArray(inputSchema?.required) ? inputSchema.required : [];
+    return toContractJsonSchema(toGeminiSchema({ type: 'object', properties, required }));
+}
+/**
+ * The tools a remote MCP server offers, as own Tools, or none when the
+ * server cannot be reached or refuses (logged, never thrown). The
+ * connection stays open for the tools' calls; closeMcpConnections ends it.
+ */
+export async function loadMcpTools(mcpServerUrl) {
     let transport;
     try {
         const url = await assertSafeMcpUrl(mcpServerUrl);
@@ -120,50 +145,17 @@ export async function createMcpTools(mcpServerUrl) {
         openTransports.add(transport);
         // Fetch available tools from the MCP server
         const toolsResponse = await client.listTools();
-        // MCP servers describe tools in standard lowercase JSON Schema; the ADK
-        // is Gemini-native and expects UPPERCASE type names. Uppercase deeply,
-        // preserving enum/description/required and nested properties/items —
-        // non-Gemini adapters normalize back to lowercase at request-build time
-        // via lib/models/schemaNormalize.ts.
-        const toGeminiSchema = (node) => {
-            if (Array.isArray(node))
-                return node.map(toGeminiSchema);
-            if (!node || typeof node !== 'object')
-                return node;
-            const out = {};
-            for (const [key, value] of Object.entries(node)) {
-                if (key === 'type') {
-                    out[key] = typeof value === 'string' ? value.toUpperCase() : value;
-                }
-                else if (key === 'enum' || key === 'required') {
-                    out[key] = value; // value lists, not schema nodes
-                }
-                else {
-                    out[key] = toGeminiSchema(value);
-                }
-            }
-            return out;
-        };
-        return toolsResponse.tools.map(tool => {
-            const properties = {};
-            const required = tool.inputSchema?.required || [];
-            if (tool.inputSchema?.properties) {
-                for (const [key, prop] of Object.entries(tool.inputSchema.properties)) {
-                    properties[key] = toGeminiSchema({
-                        ...prop,
-                        type: prop.type ?? 'string',
-                        description: prop.description || ''
-                    });
-                }
-            }
-            return new FunctionTool({
+        return toolsResponse.tools.map((tool) => {
+            // MCP servers describe tools in standard lowercase JSON Schema, which
+            // is the contract's dialect; toFunctionTool derives Gemini's.
+            const declaration = {
                 name: tool.name,
                 description: bounded(tool.description || `MCP Tool: ${tool.name}`, MAX_MCP_DESCRIPTION_CHARS, 'description'),
-                parameters: {
-                    type: 'OBJECT',
-                    properties,
-                    required
-                },
+                parameters: mcpToolParameters(tool.inputSchema),
+            };
+            return {
+                name: tool.name,
+                declaration: () => declaration,
                 execute: async (input) => {
                     try {
                         const result = await client.callTool({
@@ -177,8 +169,8 @@ export async function createMcpTools(mcpServerUrl) {
                     catch (error) {
                         return `[MCP ERROR] Tool ${tool.name} failed: ${error.message}`;
                     }
-                }
-            });
+                },
+            };
         });
     }
     catch (error) {
@@ -191,3 +183,10 @@ export async function createMcpTools(mcpServerUrl) {
         return [];
     }
 }
+/**
+ * The server's tools as the ADK runtime runs them: the FunctionTool
+ * toFunctionTool makes of each own Tool, carrying it for toolOf().
+ */
+export async function createMcpTools(mcpServerUrl) {
+    return (await loadMcpTools(mcpServerUrl)).map((tool) => toFunctionTool(tool));
+}

package/dist/lib/tools/memoryTools.d.ts

@@ -0,0 +1,61 @@
+/**
+ * lib/tools/memoryTools.ts — long-term memory's two tools, as the engine's
+ * own (ADR 0020, ADR 0051, ADR 0059).
+ *
+ * WHY this file exists:
+ *   A syndicate with `memory_system: long-term` reaches its memory through
+ *   two YAML tool names. Both were ADK's own objects (LOAD_MEMORY and
+ *   PRELOAD_MEMORY), which only ADK's loop can run. Here they are the
+ *   engine's, so the native runtime runs them, and the ADK runtime runs the
+ *   same objects through lib/tools/adkTool.ts:
+ *
+ *     load_memory     a Tool the model calls with a query. It returns the
+ *                     facts recalled for it, and while the run has memory it
+ *                     adds a note to the instruction saying memory exists.
+ *     preload_memory  an InstructionTool the model never calls. Before each
+ *                     request it recalls facts for the message that started
+ *                     the run and writes them into the instruction.
+ *
+ * WORD FOR WORD: the declaration, the note, the result's shape and the
+ * recalled block are what ADK's LoadMemoryTool and PreloadMemoryTool
+ * produced, so a model reads the same request on either runtime
+ * (tests/memoryTools.test.ts compares them with ADK's own tools).
+ *
+ * WHOSE MEMORY: both search through the context's `searchMemory`, which is
+ * bound to the run's own `<appName>/<userId>` silo; a query can choose what
+ * to recall, never whose. The runtime pins `appName` to the root syndicate's
+ * namespace (namespacedMemoryService, lib/memory/namespace.ts).
+ *
+ * Recalled facts are data the user's own conversations produced, never
+ * instructions: preload_memory fences them in a <PAST_CONVERSATIONS> block.
+ *
+ * No ADK here: nothing this module loads at runtime names @google/*.
+ */
+import { z } from 'zod';
+import type { MemoryEntry } from '../runtime/memoryService.ts';
+import type { InstructionTool } from './tool.ts';
+/** ADK's LoadMemoryTool note, word for word, line break included. */
+export declare const LOAD_MEMORY_INSTRUCTION = "You have memory. You can use it to answer questions. If any questions need\nyou to look up the memory, you should call load_memory function with a query.";
+/** What load_memory and ADK's LoadMemoryTool say when the run has no memory service. */
+export declare const NO_MEMORY_SERVICE = "Memory service is not initialized.";
+/** A memory's text: its parts' texts joined by a space, a part without text counting as empty, as ADK joins them. */
+export declare function memoryText(memory: MemoryEntry): string;
+/** One recalled memory as load_memory returns it. */
+export interface LoadedMemory {
+    content: string;
+    author?: string;
+    timestamp?: string;
+}
+export declare const loadMemoryTool: import("./toolContract.ts").DefinedTool<z.ZodObject<{
+    query: z.ZodString;
+}, z.core.$strip>, {
+    memories: LoadedMemory[];
+}>;
+/**
+ * The block preload_memory writes for the recalled memories, word for word
+ * ADK's PreloadMemoryTool's: each memory's time on its own line when it has
+ * one, then its text, prefixed by its author when it has one. Undefined when
+ * no memory has text.
+ */
+export declare function preloadMemoryInstruction(memories: MemoryEntry[]): string | undefined;
+export declare const preloadMemoryTool: InstructionTool;

package/dist/lib/tools/memoryTools.js

@@ -0,0 +1,119 @@
+/**
+ * lib/tools/memoryTools.ts — long-term memory's two tools, as the engine's
+ * own (ADR 0020, ADR 0051, ADR 0059).
+ *
+ * WHY this file exists:
+ *   A syndicate with `memory_system: long-term` reaches its memory through
+ *   two YAML tool names. Both were ADK's own objects (LOAD_MEMORY and
+ *   PRELOAD_MEMORY), which only ADK's loop can run. Here they are the
+ *   engine's, so the native runtime runs them, and the ADK runtime runs the
+ *   same objects through lib/tools/adkTool.ts:
+ *
+ *     load_memory     a Tool the model calls with a query. It returns the
+ *                     facts recalled for it, and while the run has memory it
+ *                     adds a note to the instruction saying memory exists.
+ *     preload_memory  an InstructionTool the model never calls. Before each
+ *                     request it recalls facts for the message that started
+ *                     the run and writes them into the instruction.
+ *
+ * WORD FOR WORD: the declaration, the note, the result's shape and the
+ * recalled block are what ADK's LoadMemoryTool and PreloadMemoryTool
+ * produced, so a model reads the same request on either runtime
+ * (tests/memoryTools.test.ts compares them with ADK's own tools).
+ *
+ * WHOSE MEMORY: both search through the context's `searchMemory`, which is
+ * bound to the run's own `<appName>/<userId>` silo; a query can choose what
+ * to recall, never whose. The runtime pins `appName` to the root syndicate's
+ * namespace (namespacedMemoryService, lib/memory/namespace.ts).
+ *
+ * Recalled facts are data the user's own conversations produced, never
+ * instructions: preload_memory fences them in a <PAST_CONVERSATIONS> block.
+ *
+ * No ADK here: nothing this module loads at runtime names @google/*.
+ */
+import { z } from 'zod';
+import { defineTool } from './toolContract.js';
+/** ADK's LoadMemoryTool note, word for word, line break included. */
+export const LOAD_MEMORY_INSTRUCTION = `You have memory. You can use it to answer questions. If any questions need
+you to look up the memory, you should call load_memory function with a query.`;
+/** What load_memory and ADK's LoadMemoryTool say when the run has no memory service. */
+export const NO_MEMORY_SERVICE = 'Memory service is not initialized.';
+/** A memory's text: its parts' texts joined by a space, a part without text counting as empty, as ADK joins them. */
+export function memoryText(memory) {
+    return memory.content.parts?.map((p) => p.text ?? '').join(' ') ?? '';
+}
+export const loadMemoryTool = defineTool({
+    name: 'load_memory',
+    description: 'Loads the memory for the current user.\n\nNOTE: Currently this tool only uses text part from the memory.',
+    schema: z.object({
+        query: z.string().describe('The query to load the memory for.'),
+    }),
+    async execute({ query }, ctx) {
+        if (!ctx.searchMemory)
+            throw new Error(NO_MEMORY_SERVICE);
+        try {
+            const { memories } = await ctx.searchMemory(query);
+            return {
+                memories: memories.map((m) => ({ content: memoryText(m), author: m.author, timestamp: m.timestamp })),
+            };
+        }
+        catch (err) {
+            // A failed search is the call's error, reported to the model by the
+            // runtime. The query is the user's words, so it is not logged.
+            console.error('[load_memory] Memory search failed:', err instanceof Error ? err.message : String(err));
+            throw err;
+        }
+    },
+    // Only while the run has memory: a syndicate without it is not told it has some.
+    instruction: async (ctx) => (ctx.searchMemory ? LOAD_MEMORY_INSTRUCTION : undefined),
+});
+/**
+ * The block preload_memory writes for the recalled memories, word for word
+ * ADK's PreloadMemoryTool's: each memory's time on its own line when it has
+ * one, then its text, prefixed by its author when it has one. Undefined when
+ * no memory has text.
+ */
+export function preloadMemoryInstruction(memories) {
+    const lines = [];
+    for (const memory of memories) {
+        if (memory.timestamp)
+            lines.push(`Time: ${memory.timestamp}`);
+        const text = memoryText(memory);
+        if (text)
+            lines.push(memory.author ? `${memory.author}: ${text}` : text);
+    }
+    if (lines.length === 0)
+        return undefined;
+    return `The following content is from your previous conversations with the user.
+They may be useful for answering the user's current query.
+<PAST_CONVERSATIONS>
+${lines.join('\n')}
+</PAST_CONVERSATIONS>
+`;
+}
+export const preloadMemoryTool = {
+    name: 'preload_memory',
+    /**
+     * The facts recalled for the first text part of the message that started
+     * the run. Nothing when that part has no text, the run has no memory,
+     * nothing is recalled, or the search fails: a failed recall never fails
+     * the request.
+     */
+    async instruction(ctx) {
+        const query = ctx.userContent?.parts?.[0]?.text;
+        if (!query || !ctx.searchMemory)
+            return undefined;
+        let memories;
+        try {
+            ({ memories } = await ctx.searchMemory(query));
+        }
+        catch (err) {
+            // ADK logged the query here; it is the user's words, so this does not.
+            console.warn('[preload_memory] Memory search failed; the request goes without recalled facts:', err instanceof Error ? err.message : String(err));
+            return undefined;
+        }
+        if (!memories || memories.length === 0)
+            return undefined;
+        return preloadMemoryInstruction(memories);
+    },
+};