melchizedek-agents 0.18.0 → 0.19.0

package/dist/lib/compileNative.js

@@ -0,0 +1,222 @@
+/**
+ * lib/compileNative.ts — an AgentSpec as the native runtime runs it: the
+ * NativeAgent the agent loop takes (ADR 0045, ADR 0073).
+ *
+ * WHY this file exists:
+ *   lib/compile.ts turns a YAML agent into a runtime-neutral AgentSpec, and
+ *   lib/compileAdk.ts builds ADK's LlmAgent from it. This file builds the
+ *   native loop's agent from the same spec (lib/runtime/native/request.ts,
+ *   NativeAgent), so both runtimes run the agent the YAML describes, with
+ *   the same tools, instruction and config. tests/compile.test.ts compiles
+ *   one spec both ways and requires the same first request.
+ *
+ * TOOLS: each resolved tool is handed to the loop as the own Tool or
+ * InstructionTool behind it (lib/tools/tool.ts), else as itself: an MCP
+ * tool, the skills toolset, a gated registry FunctionTool, which the loop
+ * runs by shape during the dual period (ADR 0071). A delegated subagent
+ * becomes a subagentTool holding its own NativeAgent, which the loop runs as
+ * a child loop (lib/runtime/native/delegate.ts, ADR 0074), a nested
+ * syndicate as its orchestrator's agent; a remote A2A subagent is the own
+ * Tool the ADK runtime's FunctionTool wraps (lib/a2a/remoteAgent.ts).
+ *
+ * EVERY AGENT KEY COMPILES for the native loop: `context:` is handed to
+ * the loop, which compacts as ADK does (lib/runtime/native/compaction.ts,
+ * WS2-9); `mode: task` and `code_execution: gemini` pass through, the
+ * request declaring finish_task (lib/runtime/native/taskMode.ts) and asking
+ * Gemini for its code-execution tool (lib/runtime/native/request.ts). What
+ * native does not run yet (workflows, resuming an approval or a
+ * question, a caller's agent transform) is refused by the turn runner
+ * (lib/runtime/nativeTurn.ts), which owns those choices.
+ *
+ * THE MODEL: the loop calls a model through its contract adapter. A
+ * resolver may return an id, a contract adapter, an ADK shim (which carries
+ * one) or ADK's Gemini (TracedGemini), whose key reaches the registry's
+ * Gemini adapter. Any other ADK model class has no adapter behind it, so
+ * compileNative and nativeAdapterFor refuse it with UnsupportedOnRuntimeError
+ * before any model call, naming adkShim as the way to run it on native,
+ * rather than run the registry's model for that id in its place (ADR 0088).
+ * ADK classes are told apart by ADK's own Symbol.for marks, so this file
+ * imports nothing from ADK.
+ */
+import { remoteAgentOwnTool } from './a2a/remoteAgent.js';
+import { compileSpec, compileSubagentSpec } from './compile.js';
+import { providerForModel, resolveAdapter } from './models/registry.js';
+import { subagentTool } from './runtime/native/delegate.js';
+import { unsupportedOnNative } from './runtime/runtimeFlag.js';
+export { UnsupportedOnRuntimeError, unsupportedOnNative } from './runtime/runtimeFlag.js';
+import { instructionToolOf, toolOf, toolsetOf } from './tools/tool.js';
+/** A resolved tool as the loop holds it: the own Tool, InstructionTool or Toolset behind it, else the object itself. */
+function nativeTool(tool) {
+    return toolOf(tool) ?? instructionToolOf(tool) ?? toolsetOf(tool) ?? tool;
+}
+/** ADK's own marks on its model classes (BaseLlm, Gemini), registered with Symbol.for so they hold across copies of ADK. */
+const ADK_BASE_MODEL = Symbol.for('google.adk.baseModel');
+const ADK_GEMINI_MODEL = Symbol.for('google.adk.geminiModel');
+const marked = (value, mark) => !!value && typeof value === 'object' && value[mark] === true;
+/**
+ * The class name of an ADK model the native runtime cannot run, else
+ * undefined: an ADK BaseLlm that is neither ADK's Gemini (TracedGemini
+ * included) nor a shim carrying a contract adapter (lib/models/adkShim.ts).
+ */
+export function unrunnableModelClass(resolved) {
+    if (!marked(resolved, ADK_BASE_MODEL) || marked(resolved, ADK_GEMINI_MODEL))
+        return undefined;
+    if (isModelAdapter(resolved.adapter))
+        return undefined;
+    const name = resolved.constructor?.name;
+    return typeof name === 'string' && name ? name : 'BaseLlm';
+}
+/** Throws UnsupportedOnRuntimeError when `resolved` is an ADK model class native cannot run (see the header). */
+function refuseModelClass(resolved, modelId, where) {
+    const name = unrunnableModelClass(resolved);
+    if (!name)
+        return;
+    throw unsupportedOnNative(`the ADK model class ${name} that resolveModel returned${modelId ? ` for '${modelId}'` : ''}, which has no contract adapter behind it ` +
+        `(return the ModelAdapter itself, or adkShim(adapter) from melchizedek-agents/models/adkShim, to run it on native)`, where);
+}
+/**
+ * The NativeAgent for `spec`. Throws when no model id is known, and
+ * UnsupportedOnRuntimeError when the resolver returned an ADK model class
+ * the loop cannot call (see the header).
+ */
+export function compileNative(spec) {
+    refuseModelClass(spec.resolvedModel, spec.model ?? spec.modelId, spec.name);
+    const tools = [];
+    for (const entry of spec.tools) {
+        if (entry.kind === 'agent')
+            tools.push(subagentTool(compileNative(entry.agent)));
+        else if (entry.kind === 'remote')
+            tools.push(remoteAgentOwnTool({ name: entry.name, description: entry.description, url: entry.url }));
+        else
+            tools.push(nativeTool(entry.tool));
+    }
+    const model = wireModelOf(spec);
+    if (!model)
+        throw new Error(`${spec.name}: no model id to run on (the YAML names none and the resolver returned none).`);
+    const agent = {
+        name: spec.name,
+        model,
+        instruction: spec.instruction,
+        tools,
+        generateContentConfig: spec.generateContentConfig,
+    };
+    if (spec.description)
+        agent.description = spec.description;
+    if (spec.globalInstruction !== undefined)
+        agent.globalInstruction = spec.globalInstruction;
+    if (spec.outputSchema)
+        agent.outputSchema = spec.outputSchema;
+    if (spec.includeContents !== undefined)
+        agent.includeContents = spec.includeContents;
+    if (spec.disallowTransferToParent !== undefined)
+        agent.disallowTransferToParent = spec.disallowTransferToParent;
+    if (spec.disallowTransferToPeers !== undefined)
+        agent.disallowTransferToPeers = spec.disallowTransferToPeers;
+    if (spec.codeExecution)
+        agent.codeExecution = spec.codeExecution;
+    if (spec.mode)
+        agent.mode = spec.mode;
+    if (spec.outputKey !== undefined)
+        agent.outputKey = spec.outputKey;
+    if (spec.fallbackModel)
+        agent.fallbackModel = spec.fallbackModel;
+    if (spec.context)
+        agent.context = spec.context;
+    return agent;
+}
+/**
+ * The model id a request is sent under, as ADK's LlmAgent sends it: the id
+ * of the model object the resolver returned (an ADK model or a contract
+ * adapter carries its own), else the id the resolver returned, else the
+ * spec's. A resolver may answer a YAML id with a model under another id (a
+ * gateway stand-in, a caller's alias); the adapter, the span and the
+ * circuit breaker then see that id on both runtimes.
+ */
+export function wireModelOf(spec) {
+    const resolved = spec.resolvedModel;
+    if (typeof resolved === 'string' && resolved)
+        return resolved;
+    const own = resolved && typeof resolved === 'object' ? resolved.model : undefined;
+    if (typeof own === 'string' && own)
+        return own;
+    return spec.modelId;
+}
+/** A syndicate's orchestrator for the native loop: compileSpec, then compileNative. */
+export async function compileNativeGraph(config, opts = {}) {
+    return compileNative(await compileSpec(config, opts));
+}
+/** One subagent entry (a dispatch route) for the native loop: compileSubagentSpec, then compileNative. */
+export async function compileNativeSubagent(subCfg, opts = {}) {
+    return compileNative(await compileSubagentSpec(subCfg, opts));
+}
+function isModelAdapter(value) {
+    return !!value && typeof value === 'object' && typeof value.generate === 'function' && typeof value.model === 'string';
+}
+/**
+ * The contract adapter behind what a resolver returned: an ADK shim's own
+ * adapter; for an ADK class that is not a shim (TracedGemini, ADK's Gemini)
+ * the registry's adapter under the key the instance carries, so a caller's
+ * BYOK key still pays for the call; else the registry's for the id.
+ */
+function adapterOf(resolved, model) {
+    if (isModelAdapter(resolved))
+        return resolved;
+    refuseModelClass(resolved, model, 'the native runtime');
+    if (typeof resolved === 'string')
+        return resolveAdapter(resolved || model);
+    if (!resolved || typeof resolved !== 'object')
+        return resolveAdapter(model);
+    const held = resolved;
+    if (isModelAdapter(held.adapter))
+        return held.adapter;
+    // On Vertex AI the client authenticates with the platform's credentials, never a key (ADR 0023).
+    if (typeof held.apiKey === 'string' && held.apiKey && held.vertexai !== true) {
+        return resolveAdapter(model, { apiKey: held.apiKey, keyProvider: providerForModel(model) });
+    }
+    return resolveAdapter(model);
+}
+/**
+ * The loop's `adapterFor` under the same model resolution the ADK runtime
+ * uses: the leaf adapter behind what CompileOptions.resolveModel returns
+ * (an ADK shim carries its contract adapter, so a caller's BYOK key on a
+ * shimmed provider reaches the call), else resolveAdapter for the id
+ * (lib/models/registry.ts). The spec's own resolution, and each delegated
+ * subagent's, is reused for the id its agent runs under (wireModelOf).
+ * Each agent's `fallback_model:` and compaction `summary_model` are
+ * resolved here, as compileAdk resolves them at compile time, so a model
+ * class native cannot run is refused before any model call; any other id
+ * is resolved when first asked for. Each is kept.
+ */
+export function nativeAdapterFor(opts = {}, spec) {
+    const cache = new Map();
+    const known = new Map();
+    const learn = (s) => {
+        if (s.resolvedModel !== undefined) {
+            for (const id of [wireModelOf(s), s.modelId])
+                if (id && !known.has(id))
+                    known.set(id, s.resolvedModel);
+        }
+        for (const id of [s.fallbackModel, s.context?.summary_model]) {
+            if (!id || known.has(id) || !opts.resolveModel)
+                continue;
+            const resolved = opts.resolveModel(id);
+            refuseModelClass(resolved, id, s.name ?? 'the native runtime');
+            known.set(id, resolved);
+        }
+        for (const entry of s.tools ?? [])
+            if (entry.kind === 'agent')
+                learn(entry.agent);
+    };
+    // A workflow's agents share one lookup: every node's spec is learned.
+    for (const s of spec === undefined ? [] : Array.isArray(spec) ? spec : [spec])
+        learn(s);
+    return (model) => {
+        const held = cache.get(model);
+        if (held)
+            return held;
+        const resolved = known.has(model) ? known.get(model) : opts.resolveModel ? opts.resolveModel(model) : model;
+        const adapter = adapterOf(resolved, model);
+        cache.set(model, adapter);
+        return adapter;
+    };
+}

package/dist/lib/config.d.ts

@@ -52,11 +52,12 @@ export declare const DEFAULT_GPT_MODEL = "gpt-5-mini";
  */
 export declare const DEFAULT_GROK_MODEL = "grok-4.7";
 /**
- * Reasoning effort sent with grok-4.5/4.7 requests: 'low' | 'medium' | 'high'
- * (xAI's own default is 'high'; 4.7 adds 'xhigh'). Pinned to MEDIUM — deeper
- * than low without high's latency and token cost. Source: docs.x.ai › Model
- * capabilities › Text › Reasoning › Effort levels. Older grok ids don't
- * accept the param and never receive it (lib/models/grokLlm.ts).
+ * Reasoning effort sent with grok-4.5, 4.6 and 4.7 requests that set no
+ * `reasoning:`: 'low' | 'medium' | 'high' (xAI's own default is 'high'; 4.7
+ * adds 'xhigh'). Pinned to MEDIUM — deeper than low without high's latency
+ * and token cost. Source: docs.x.ai › Model capabilities › Text › Reasoning ›
+ * Effort levels. Older grok ids don't accept the param and never receive it
+ * (lib/models/grokAdapter.ts).
  */
 export declare const DEFAULT_GROK_REASONING_EFFORT = "medium";
 /**

package/dist/lib/config.js

@@ -53,11 +53,12 @@ export const DEFAULT_GPT_MODEL = 'gpt-5-mini';
  */
 export const DEFAULT_GROK_MODEL = 'grok-4.7';
 /**
- * Reasoning effort sent with grok-4.5/4.7 requests: 'low' | 'medium' | 'high'
- * (xAI's own default is 'high'; 4.7 adds 'xhigh'). Pinned to MEDIUM — deeper
- * than low without high's latency and token cost. Source: docs.x.ai › Model
- * capabilities › Text › Reasoning › Effort levels. Older grok ids don't
- * accept the param and never receive it (lib/models/grokLlm.ts).
+ * Reasoning effort sent with grok-4.5, 4.6 and 4.7 requests that set no
+ * `reasoning:`: 'low' | 'medium' | 'high' (xAI's own default is 'high'; 4.7
+ * adds 'xhigh'). Pinned to MEDIUM — deeper than low without high's latency
+ * and token cost. Source: docs.x.ai › Model capabilities › Text › Reasoning ›
+ * Effort levels. Older grok ids don't accept the param and never receive it
+ * (lib/models/grokAdapter.ts).
  */
 export const DEFAULT_GROK_REASONING_EFFORT = 'medium';
 /**

package/dist/lib/doctor.js

@@ -155,6 +155,7 @@ function needsOf(agent, delegates = false) {
         tools: agent.tools ?? [],
         outputSchema: agent.outputSchema,
         generateContentConfig: agent.generateContentConfig,
+        reasoning: agent.reasoning,
         delegates,
     };
 }

package/dist/lib/index.d.ts

@@ -37,7 +37,8 @@ export type { RemoteAnswer } from './a2a/remoteAgent.ts';
 export { resolveTools, registerTool, registeredToolNames } from './toolRegistry.ts';
 export { registerGuard, resolveGuards } from './guards/index.ts';
 export type { Guard, GuardResult } from './guards/index.ts';
-export { defineTool, toFunctionTool } from './tools/toolContract.ts';
+export { defineTool } from './tools/toolContract.ts';
+export { toFunctionTool } from './tools/adkTool.ts';
 export { modelExtractor, geminiEmbedder, openAiCompatibleEmbedder, memoryProvidersFromEnv, } from './memory/providers.ts';
 export type { Embedder, MemoryExtractor } from './memory/providers.ts';
 export { eraseScope } from './memory/erase.ts';

package/dist/lib/index.js

@@ -28,7 +28,8 @@ export { RemoteA2AAgent, remoteAgentTool } from './a2a/remoteAgent.js';
 // ── Extend it ───────────────────────────────────────────────────────────────
 export { resolveTools, registerTool, registeredToolNames } from './toolRegistry.js';
 export { registerGuard, resolveGuards } from './guards/index.js';
-export { defineTool, toFunctionTool } from './tools/toolContract.js';
+export { defineTool } from './tools/toolContract.js';
+export { toFunctionTool } from './tools/adkTool.js';
 // ── Memory ──────────────────────────────────────────────────────────────────
 export { modelExtractor, geminiEmbedder, openAiCompatibleEmbedder, memoryProvidersFromEnv, } from './memory/providers.js';
 export { eraseScope } from './memory/erase.js';

package/dist/lib/loadSyndicate.d.ts

@@ -6,6 +6,7 @@ import type { ContextConfig, ExampleConfig } from './compile.ts';
 export type { OpenApiConfig } from './tools/openapiTools.ts';
 export type { SkillsConfig } from './tools/skillToolset.ts';
 import type { WorkflowConfig } from './workflowConfig.ts';
+import type { ReasoningSetting } from './models/contract.ts';
 export type { WorkflowConfig } from './workflowConfig.ts';
 export interface ThinkingConfig {
     /** Token budget for internal reasoning. 0 = off, -1 = dynamic. */
@@ -13,6 +14,14 @@ export interface ThinkingConfig {
     /** Stream the thinking trace in the response. */
     includeThoughts?: boolean;
 }
+/**
+ * How hard an agent reasons, on any provider (ADR 0047): a level, or a token
+ * budget. The engine's model contract (lib/models/contract.ts) defines it.
+ * The compiler maps it to the field the agent's provider reads
+ * (lib/compile.ts reasoningConfig); `thinkingConfig` and `reasoningEffort`
+ * inside generateContentConfig are the older, provider-specific spelling.
+ */
+export type { ReasoningLevel, ReasoningSetting } from './models/contract.ts';
 export interface SafetySetting {
     category: string;
     threshold: string;
@@ -35,7 +44,10 @@ export interface GenerateContentConfig {
     seed?: number;
     responseMimeType?: string;
     safetySettings?: SafetySetting[];
+    /** Older spelling of `reasoning` for Gemini and Claude (ADR 0047). */
     thinkingConfig?: ThinkingConfig;
+    /** Older spelling of `reasoning` for the chat-completions providers (ADR 0047). */
+    reasoningEffort?: string;
 }
 /**
  * Maps to LlmAgentConfig (+ BaseAgentConfig) from @google/adk.
@@ -82,6 +94,12 @@ export interface AgentYamlConfig {
      * Maps to LlmAgentConfig.generateContentConfig.
      */
     generateContentConfig?: GenerateContentConfig;
+    /**
+     * How hard the agent reasons: none | low | medium | high, or
+     * { budget_tokens }. Cannot be combined with generateContentConfig's
+     * thinkingConfig or reasoningEffort (ADR 0047).
+     */
+    reasoning?: ReasoningSetting;
     /**
      * Output schema for structured JSON responses.
      * Maps to LlmAgentConfig.outputSchema.

package/dist/lib/memory/erase.d.ts

@@ -5,8 +5,10 @@
  * which deletes memory facts, sessions (with the per-subagent rows ADK writes
  * beside them), the ledger's turns, spans, payloads, verdicts and labels, the
  * scope's durable A2A tasks for those conversations, its memory ingestion
- * markers, and (without a namespace) its task tools' list and jobs
- * (migration 0010), in one transaction. Returns what each store lost.
+ * markers, (without a namespace) its task tools' list and jobs
+ * (migration 0010), and the third-party tokens held for its tools, every
+ * app's or the namespace's own (migration 0013), in one transaction.
+ * Returns what each store lost.
  *
  * With a namespace, ledger turns and A2A tasks are kept only when their
  * conversation is still live in another namespace (migration 0011): they do
@@ -17,7 +19,7 @@
  * worse than an error the caller can surface and retry.
  */
 import type { SupabaseClient } from '@supabase/supabase-js';
-export declare const ERASE_STORES: readonly ['memory_facts', 'sessions', 'turns', 'spans', 'payloads', 'verdicts', 'labels', 'tasks', 'memory_markers', 'task_tools'];
+export declare const ERASE_STORES: readonly ['memory_facts', 'sessions', 'turns', 'spans', 'payloads', 'verdicts', 'labels', 'tasks', 'memory_markers', 'task_tools', 'credentials'];
 export type EraseStore = (typeof ERASE_STORES)[number];
 export type EraseCounts = Record<EraseStore, number>;
 export interface EraseOptions {

package/dist/lib/memory/erase.js

@@ -5,8 +5,10 @@
  * which deletes memory facts, sessions (with the per-subagent rows ADK writes
  * beside them), the ledger's turns, spans, payloads, verdicts and labels, the
  * scope's durable A2A tasks for those conversations, its memory ingestion
- * markers, and (without a namespace) its task tools' list and jobs
- * (migration 0010), in one transaction. Returns what each store lost.
+ * markers, (without a namespace) its task tools' list and jobs
+ * (migration 0010), and the third-party tokens held for its tools, every
+ * app's or the namespace's own (migration 0013), in one transaction.
+ * Returns what each store lost.
  *
  * With a namespace, ledger turns and A2A tasks are kept only when their
  * conversation is still live in another namespace (migration 0011): they do
@@ -27,6 +29,7 @@ export const ERASE_STORES = [
     'tasks',
     'memory_markers',
     'task_tools',
+    'credentials',
 ];
 export async function eraseScope(client, scopeKey, options = {}) {
     if (!scopeKey?.trim())

package/dist/lib/memory/namespace.d.ts

@@ -9,10 +9,17 @@
  * nothing, and said so without error. Wrapping the service the runtime hands
  * to ADK pins every search and ingestion to one namespace, whatever app
  * name the caller carries.
+ *
+ * The pin covers both interfaces a service may implement: ADK's
+ * (`searchMemory`, `addSessionToMemory`) and the engine's MemoryService
+ * (`search`, `ingest`, lib/runtime/memoryService.ts, ADR 0059). Every other
+ * member, erase and retention included, passes through unchanged: they name
+ * their key or namespace themselves.
  */
 import type { BaseMemoryService } from '@google/adk';
+import type { MemoryService } from '../runtime/memoryService.ts';
 /** A memory service whose every read and write uses `namespace` as the app name. */
-export declare function namespacedMemoryService<T extends BaseMemoryService>(base: T, namespace: string): T;
+export declare function namespacedMemoryService<T extends BaseMemoryService | MemoryService>(base: T, namespace: string): T;
 /** The server-wide name memory falls back to when a syndicate declares none. */
 export declare const LEGACY_MEMORY_APP_NAME = "melchizedek-a2a";
 /**

package/dist/lib/memory/namespace.js

@@ -9,23 +9,29 @@
  * nothing, and said so without error. Wrapping the service the runtime hands
  * to ADK pins every search and ingestion to one namespace, whatever app
  * name the caller carries.
+ *
+ * The pin covers both interfaces a service may implement: ADK's
+ * (`searchMemory`, `addSessionToMemory`) and the engine's MemoryService
+ * (`search`, `ingest`, lib/runtime/memoryService.ts, ADR 0059). Every other
+ * member, erase and retention included, passes through unchanged: they name
+ * their key or namespace themselves.
  */
 import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+/** The four methods whose first argument carries the app name the pin replaces. */
+const PINNED = new Set(['searchMemory', 'addSessionToMemory', 'search', 'ingest']);
 /** A memory service whose every read and write uses `namespace` as the app name. */
 export function namespacedMemoryService(base, namespace) {
     if (!namespace)
         throw new Error('namespacedMemoryService: namespace is required');
     return new Proxy(base, {
         get(target, prop, receiver) {
-            if (prop === 'searchMemory') {
-                return (request) => target.searchMemory({ ...request, appName: namespace });
-            }
-            if (prop === 'addSessionToMemory') {
-                return (session, ...rest) => target.addSessionToMemory.call(target, { ...session, appName: namespace }, ...rest);
-            }
             const value = Reflect.get(target, prop, receiver);
+            if (PINNED.has(prop) && typeof value === 'function') {
+                // A search request or a session: the same object with the namespace as its app name.
+                return (first, ...rest) => value.call(target, { ...first, appName: namespace }, ...rest);
+            }
             return typeof value === 'function' ? value.bind(target) : value;
         },
     });

package/dist/lib/memory/providers.js

@@ -35,6 +35,7 @@ import { EMBEDDING_DIMENSIONS, EMBEDDING_MODEL, MEMORY_EXTRACTION_MODEL } from '
 import { providerForModel } from '../models/providerMap.js';
 import { resolveModel } from '../models/registry.js';
 import { initializeTracing } from '../observability/tracer.js';
+import { trimTrailingSlashes } from '../models/urls.js';
 /**
  * Extraction on any model id. The key passed here reaches only a model of
  * the matching provider (resolveModel's BYOK rule); other providers read
@@ -146,7 +147,7 @@ export function geminiEmbedder(opts) {
 export function openAiCompatibleEmbedder(opts) {
     const dimensions = opts.dimensions ?? EMBEDDING_DIMENSIONS;
     const provider = opts.provider ?? 'openai-compatible';
-    const url = `${opts.baseUrl.replace(/\/+$/, '')}/embeddings`;
+    const url = `${trimTrailingSlashes(opts.baseUrl)}/embeddings`;
     return {
         provider,
         model: opts.model,

package/dist/lib/memory/supabaseMemoryService.d.ts

@@ -1,5 +1,21 @@
-import type { BaseMemoryService, SearchMemoryRequest, SearchMemoryResponse, Session } from '@google/adk';
+/**
+ * lib/memory/supabaseMemoryService.ts — long-term memory over pgvector
+ * (ADR 0020), on the engine's own interface and on ADK's.
+ *
+ * The class implements the engine's MemoryService (lib/runtime/memoryService.ts:
+ * `ingest`, `search`, and the optional `deleteUserMemory`, `pruneExpired`
+ * and `verifyEmbeddingDimensions`, ADR 0052), which the native runtime and
+ * the engine's own memory tools (lib/tools/memoryTools.ts) call. It also
+ * implements ADK's BaseMemoryService, whose `addSessionToMemory` and
+ * `searchMemory` the ADK runtime's Runner, the turn runner's ingestion
+ * (ingestTurnMemory) and the A2A server call: each is one line that hands
+ * its arguments to `ingest` or `search`, so both runtimes reach the same
+ * logic and the same silos (ADR 0059).
+ */
+import type { BaseMemoryService, SearchMemoryRequest, SearchMemoryResponse, Session as AdkSession } from '@google/adk';
 import type { SupabaseClient } from '@supabase/supabase-js';
+import type { MemoryIngestOptions, MemorySearchRequest, MemorySearchResult, MemoryService } from '../runtime/memoryService.ts';
+import type { Session } from '../runtime/sessions.ts';
 import type { MemoryStore } from './store.ts';
 import type { Embedder, MemoryExtractor } from './providers.ts';
 /**
@@ -51,7 +67,7 @@ export declare function isSemanticDuplicate(candidate: {
     status: string | null;
     similarity: number;
 }>, threshold?: number): boolean;
-export declare class SupabaseVectorMemoryService implements BaseMemoryService {
+export declare class SupabaseVectorMemoryService implements MemoryService, BaseMemoryService {
     private extractor;
     private embedder;
     private store;
@@ -90,15 +106,26 @@ export declare class SupabaseVectorMemoryService implements BaseMemoryService {
         extractorFor?: (model: string) => MemoryExtractor;
     }, backend: SupabaseClient | MemoryStore);
     /**
+     * ADK's name for `ingest`, which the ADK runtime and the A2A server call.
+     *
      * @param extractionRules Optional domain rules appended to the shared
      *   extraction prompt for THIS consumer only. The prompt is global (the
      *   patient advocate uses the same one), so anything domain-specific —
      *   "never store a market quote" — arrives here rather than being edited
      *   into it. Declared as `memory_extraction_rules` on the served syndicate.
      */
-    addSessionToMemory(session: Session, extractionRules?: string, options?: {
+    addSessionToMemory(session: AdkSession, extractionRules?: string, options?: {
         extractionModel?: string;
     }): Promise<void>;
+    /**
+     * Distils the session's events not yet ingested into facts filed under
+     * `<appName>/<userId>`. Throws when a step fails, leaving those events
+     * pending for the next ingestion (ADR 0020 item 6).
+     *
+     * @param options.extractionRules The syndicate's `memory_extraction_rules`.
+     * @param options.extractionModel The syndicate's `memory_extraction_model`.
+     */
+    ingest(session: Session, options?: MemoryIngestOptions): Promise<void>;
     /**
      * Right-to-erasure: permanently deletes every stored fact for a user key
      * (`{appName}/{userId}`). Returns the number of rows removed. Throws on
@@ -109,7 +136,14 @@ export declare class SupabaseVectorMemoryService implements BaseMemoryService {
      * `adk_sessions` and must be cleared separately if full erasure is needed.
      */
     deleteUserMemory(userKey: string): Promise<number>;
+    /**
+     * ADK's name for `search`, which ADK's Context.searchMemory calls. The
+     * entries are the same JSON as ADK's MemoryEntry; only genai's types name
+     * a few part fields as enums, hence the cast.
+     */
     searchMemory(request: SearchMemoryRequest): Promise<SearchMemoryResponse>;
+    /** The facts most relevant to the query, from the `<appName>/<userId>` silo only. */
+    search(request: MemorySearchRequest): Promise<MemorySearchResult>;
     /**
      * The extractor for a syndicate's `memory_extraction_model` (ADR 0020
      * item 4), or the deployment's. The server's Gemini key reaches only a

package/dist/lib/memory/supabaseMemoryService.js

@@ -1,3 +1,17 @@
+/**
+ * lib/memory/supabaseMemoryService.ts — long-term memory over pgvector
+ * (ADR 0020), on the engine's own interface and on ADK's.
+ *
+ * The class implements the engine's MemoryService (lib/runtime/memoryService.ts:
+ * `ingest`, `search`, and the optional `deleteUserMemory`, `pruneExpired`
+ * and `verifyEmbeddingDimensions`, ADR 0052), which the native runtime and
+ * the engine's own memory tools (lib/tools/memoryTools.ts) call. It also
+ * implements ADK's BaseMemoryService, whose `addSessionToMemory` and
+ * `searchMemory` the ADK runtime's Runner, the turn runner's ingestion
+ * (ingestTurnMemory) and the A2A server call: each is one line that hands
+ * its arguments to `ingest` or `search`, so both runtimes reach the same
+ * logic and the same silos (ADR 0059).
+ */
 import { memoryProvidersFromEnv, modelExtractor } from './providers.js';
 import { providerForModel } from '../models/providerMap.js';
 import { isSupabaseClient, supabaseMemoryStore } from './store.js';
@@ -13,7 +27,9 @@ import { isSupabaseClient, supabaseMemoryStore } from './store.js';
  */
 export function stripHarnessBlocks(text) {
     return text
-        .replace(/\[System Context:[^\]]*\]\s*/g, '')
+        // `[^[\]]` stops at any bracket, so a run of unclosed markers is
+        // scanned once, not once per marker (CodeQL js/polynomial-redos).
+        .replace(/\[System Context:[^[\]]*\]\s*/g, '')
         // A data block a calling surface attaches: a bracketed label ending in
         // "Payload" or "Sheet" (e.g. `[Account Payload]`), then a fenced block.
         .replace(/\[[A-Za-z][A-Za-z ]{0,60}(?:Payload|Sheet)\]\s*```[\s\S]*?```\s*/g, '')
@@ -147,6 +163,8 @@ export class SupabaseVectorMemoryService {
             + `extraction ${this.extractor.model}, embeddings ${this.embedder.provider}/${this.embedder.model} (${this.embedder.dimensions}d)`);
     }
     /**
+     * ADK's name for `ingest`, which the ADK runtime and the A2A server call.
+     *
      * @param extractionRules Optional domain rules appended to the shared
      *   extraction prompt for THIS consumer only. The prompt is global (the
      *   patient advocate uses the same one), so anything domain-specific —
@@ -154,6 +172,18 @@ export class SupabaseVectorMemoryService {
      *   into it. Declared as `memory_extraction_rules` on the served syndicate.
      */
     async addSessionToMemory(session, extractionRules, options = {}) {
+        return this.ingest(session, { extractionRules, extractionModel: options.extractionModel });
+    }
+    /**
+     * Distils the session's events not yet ingested into facts filed under
+     * `<appName>/<userId>`. Throws when a step fails, leaving those events
+     * pending for the next ingestion (ADR 0020 item 6).
+     *
+     * @param options.extractionRules The syndicate's `memory_extraction_rules`.
+     * @param options.extractionModel The syndicate's `memory_extraction_model`.
+     */
+    async ingest(session, options = {}) {
+        const { extractionRules } = options;
         const userKey = `${session.appName}/${session.userId}`;
         const watermarkKey = `${userKey}::${session.id}`;
         let alreadyIngested = this.ingestedEventCount.get(watermarkKey) ?? 0;
@@ -238,9 +268,19 @@ export class SupabaseVectorMemoryService {
         console.log(`[MemoryService] Deleted ${count} fact(s) for user key: ${userKey}`);
         return count;
     }
+    /**
+     * ADK's name for `search`, which ADK's Context.searchMemory calls. The
+     * entries are the same JSON as ADK's MemoryEntry; only genai's types name
+     * a few part fields as enums, hence the cast.
+     */
     async searchMemory(request) {
+        return (await this.search(request));
+    }
+    /** The facts most relevant to the query, from the `<appName>/<userId>` silo only. */
+    async search(request) {
         const query = stripHarnessBlocks(request.query) || request.query;
-        console.log(`[MemoryService] Searching memory for: "${query}"`);
+        // The query is the user's own words: the log says only how long it is.
+        console.log(`[MemoryService] Searching memory (${query.length} chars)`);
         const userKey = `${request.appName}/${request.userId}`;
         return this.searchSupabase(userKey, query);
     }