melchizedek-agents 1.0.0 → 1.0.1

package/dist/lib/tools/adkTool.js

@@ -1,268 +0,0 @@
-/**
- * lib/tools/adkTool.ts — the boundary where an own Tool becomes an ADK tool.
- *
- * WHY this file exists:
- *   Tools are the engine's own (lib/tools/tool.ts, ADR 0051): a name, the
- *   declaration the model receives, and `execute(args, ctx)`. Until 1.0.0
- *   removes ADK (ADR 0045) the ADK runtime runs the same tools, and this
- *   module is the one place that turns a Tool into what ADK consumes: a
- *   FunctionTool whose Gemini-dialect parameters come from the Tool's
- *   declaration, and whose execute hands the Tool a ToolContext read from
- *   ADK's own Context. Nothing else in lib/tools builds an ADK tool from an
- *   own Tool, and tool.ts and toolContract.ts import nothing from ADK.
- *
- *   The ADK runtime behaves as it did when every tool was a FunctionTool:
- *   - the declaration ADK sends is the Tool's, in Gemini's dialect
- *     (toGeminiSchema), so contractToolDeclaration reads the same
- *     parameters through either path;
- *   - a long-running Tool is a long-running FunctionTool, and its pending
- *     (undefined) result is the null response ADK waits on;
- *   - a Tool that requires approval sets FunctionTool's own gate, which
- *     raises `adk_request_confirmation` as lib/compile.ts's gate does;
- *   - a Tool that throws becomes ADK's `Error in tool '<name>': …` response;
- *   - a Tool's `instruction`, and an InstructionTool's, are appended to the
- *     request's system instruction in the tool's processLlmRequest, joined
- *     as ADK's own appendInstructions joins them, at the tool's place in the
- *     agent's list: where ADK's load_memory and preload_memory wrote theirs
- *     (ADR 0059);
- *   - the context reaches the run's memory through ADK's own
- *     `Context.searchMemory`, so a search reads the silo ADK's tools read;
- *   - a NativeToolMarker is the shared sentinel the ADK runtime always ran
- *     for that server-side tool, which carries the same marker (ADR 0062);
- *   - a Tool's `contents` hook adds to the request's history in the tool's
- *     processLlmRequest, where ADK's load_skill_resource added a binary
- *     file (ADR 0083);
- *   - an own Toolset (the skills harness) is a BaseToolset whose getTools
- *     lists the Toolset's tools for ADK's ReadonlyContext, each through
- *     toAdkTool (ADR 0083).
- *
- *   toAdkTool takes any of these and picks the wrapper.
- */
-import { BaseTool, BaseToolset, FunctionTool, GOOGLE_SEARCH } from '../adkPeer.js';
-import { currentTurnSignal } from '../runtime/turnControl.js';
-import { COLLECTIONS_SEARCH } from './collectionsSearchTool.js';
-import { OWN_TOOL, createToolContext, isInstructionTool, isNativeToolMarker, isOwnToolset, nativeToolMarkerOf } from './tool.js';
-import { URL_CONTEXT } from './urlContextTool.js';
-import { WEB_SEARCH } from './webSearchTool.js';
-import { X_SEARCH } from './xSearchTool.js';
-import { asTool, toGeminiSchema, toolCallContextFrom } from './toolContract.js';
-/**
- * ADK's Context seen as a ToolContext. Who the call is for is copied once;
- * the rest reads through to ADK's Context, so a state write lands in ADK's
- * own delta and `actions` is the event's actions.
- */
-class AdkToolContext {
-    userId;
-    appName;
-    sessionId;
-    #adk;
-    #fallback;
-    constructor(adk) {
-        this.#adk = adk;
-        const who = toolCallContextFrom(adk);
-        this.userId = who?.userId;
-        this.appName = who?.appName;
-        this.sessionId = who?.sessionId;
-    }
-    /** A stand-in for the parts a partial Context (a test's) lacks. */
-    get #local() {
-        return (this.#fallback ??= createToolContext());
-    }
-    get invocationId() {
-        return this.#adk.invocationContext?.invocationId;
-    }
-    get agentName() {
-        const agent = this.#adk.invocationContext?.agent;
-        return agent?.name;
-    }
-    get functionCallId() {
-        return this.#adk.functionCallId;
-    }
-    get state() {
-        return this.#adk.state ?? this.#local.state;
-    }
-    get stateDelta() {
-        return this.#adk.actions?.stateDelta ?? this.#local.stateDelta;
-    }
-    get actions() {
-        return this.#adk.actions ?? this.#local.actions;
-    }
-    requestConfirmation(request = {}) {
-        this.#adk.requestConfirmation({ hint: request.hint, payload: request.payload });
-    }
-    get confirmation() {
-        const c = this.#adk.toolConfirmation;
-        return c ? { confirmed: c.confirmed, hint: c.hint, payload: c.payload } : undefined;
-    }
-    get signal() {
-        return this.#adk.abortSignal ?? currentTurnSignal();
-    }
-    get userContent() {
-        return this.#adk.invocationContext?.userContent;
-    }
-    /**
-     * ADK's own search: the run's memory service, under the session's app name
-     * and user id. Absent when the run has no memory service.
-     */
-    get searchMemory() {
-        if (!this.#adk.invocationContext?.memoryService)
-            return undefined;
-        return (query) => this.#adk.searchMemory(query);
-    }
-}
-/** The ToolContext for one ADK call; a standalone one outside a run. */
-export function adkToolContext(adkContext) {
-    return adkContext && typeof adkContext === 'object' ? new AdkToolContext(adkContext) : createToolContext();
-}
-export function toFunctionTool(tool) {
-    const own = asTool(tool);
-    const declaration = own.declaration();
-    const options = {
-        name: own.name,
-        description: declaration.description,
-        parameters: toGeminiSchema(declaration.parameters),
-        execute: (args, adkContext) => own.execute((args ?? {}), adkToolContext(adkContext)),
-        isLongRunning: own.longRunning === true,
-        requireConfirmation: own.requiresApproval === true,
-    };
-    // Only a Tool that writes into the request needs more than FunctionTool.
-    const writes = typeof own.instruction === 'function' || typeof own.contents === 'function';
-    const adkTool = writes ? new InstructingFunctionTool(options) : new FunctionTool(options);
-    Object.defineProperty(adkTool, OWN_TOOL, { value: own });
-    return adkTool;
-}
-// ── Writing into the instruction (ADR 0059) ──────────────────────────────────
-/**
- * Appends to the request's system instruction exactly as ADK's own
- * appendInstructions (models/llm_request.js, not exported) does: the texts
- * joined by a blank line, after a blank line when there is one already.
- */
-function appendInstruction(llmRequest, text) {
-    llmRequest.config ??= {};
-    const config = llmRequest.config;
-    config.systemInstruction = config.systemInstruction ? `${config.systemInstruction}\n\n${text}` : text;
-}
-/**
- * The own tool an ADK tool carries. Read through `this`, not a private
- * field, so the copy lib/compile.ts makes with Object.create to gate a tool
- * still finds it.
- */
-function carried(adkTool) {
-    return adkTool[OWN_TOOL];
-}
-/** A FunctionTool that also writes its Tool's instruction and contents, after declaring itself. */
-class InstructingFunctionTool extends FunctionTool {
-    async processLlmRequest(request) {
-        await super.processLlmRequest(request);
-        const own = carried(this);
-        const text = await own.instruction?.(adkToolContext(request.toolContext));
-        if (text)
-            appendInstruction(request.llmRequest, text);
-        if (own.contents && request.llmRequest.contents) {
-            await own.contents(request.llmRequest.contents, adkToolContext(request.toolContext));
-        }
-    }
-}
-/** The ADK tool for an InstructionTool: declares nothing, and appends its instruction. */
-class InstructionOnlyTool extends BaseTool {
-    async runAsync() {
-        throw new Error(`${this.name} only writes into the instruction and is never called by a model`);
-    }
-    async processLlmRequest(request) {
-        await super.processLlmRequest(request);
-        const text = await carried(this).instruction(adkToolContext(request.toolContext));
-        if (text)
-            appendInstruction(request.llmRequest, text);
-    }
-}
-/**
- * ADK surface for an InstructionTool: a BaseTool that declares no function,
- * so it never enters the request's tools, and appends the InstructionTool's
- * text in processLlmRequest, where ADK's PreloadMemoryTool appended its own.
- * instructionToolOf (lib/tools/tool.ts) reads the InstructionTool back.
- */
-export function toAdkInstructionTool(tool) {
-    // ADK reads neither name nor description from a tool that declares
-    // nothing; ADK's PreloadMemoryTool used its name for both.
-    const adkTool = new InstructionOnlyTool({ name: tool.name, description: tool.name });
-    Object.defineProperty(adkTool, OWN_TOOL, { value: tool });
-    return adkTool;
-}
-// ── Server-side tools (ADR 0062) ─────────────────────────────────────────────
-/**
- * The ADK runtime's object for each NativeTool a marker may name: the
- * engine's sentinels, which carry the same marker, and ADK's own
- * GOOGLE_SEARCH. Code execution is the agent's `code_execution: gemini`,
- * never a listed tool, so it has none.
- */
-const ADK_NATIVE_TOOLS = {
-    web_search: WEB_SEARCH,
-    x_search: X_SEARCH,
-    url_context: URL_CONTEXT,
-    collections_search: COLLECTIONS_SEARCH,
-    google_search: GOOGLE_SEARCH,
-};
-/**
- * ADK surface for a NativeToolMarker: the shared sentinel the ADK runtime
- * has always run for it, which during processLlmRequest leaves itself in
- * the request for the adapter (or adds Gemini's own tool object).
- */
-export function toAdkNativeTool(marker) {
-    const native = nativeToolMarkerOf(marker);
-    const adkTool = native ? ADK_NATIVE_TOOLS[native] : undefined;
-    if (!adkTool) {
-        throw new Error(`${marker.name} names no server-side tool an agent can list (code execution is an agent's code_execution: gemini)`);
-    }
-    return adkTool;
-}
-// ── Toolsets (ADR 0083) ──────────────────────────────────────────────────────
-/**
- * The ADK toolset for an own Toolset: getTools hands the Toolset ADK's
- * ReadonlyContext (its agent name, invocation id and state are what a
- * ToolsetContext reads) and returns each tool through toAdkTool, the same
- * FunctionTool for the same Tool on every request. toolsetOf
- * (lib/tools/tool.ts) reads the Toolset back.
- */
-class OwnToolsetAdapter extends BaseToolset {
-    #wrapped = new WeakMap();
-    constructor(toolset) {
-        super([]);
-        Object.defineProperty(this, OWN_TOOL, { value: toolset });
-    }
-    async getTools(context) {
-        const own = carried(this);
-        const tools = await own.getTools(context);
-        return tools.map((tool) => {
-            if (!tool || typeof tool !== 'object')
-                throw new Error(`${own.name ?? 'toolset'} listed a tool that is not an object`);
-            let adk = this.#wrapped.get(tool);
-            if (!adk) {
-                adk = toAdkTool(tool);
-                this.#wrapped.set(tool, adk);
-            }
-            return adk;
-        });
-    }
-    async close() { }
-}
-/** ADK surface for an own Toolset: a BaseToolset carrying it. */
-export function toAdkToolset(toolset) {
-    return new OwnToolsetAdapter(toolset);
-}
-/**
- * What the engine holds as a tool, as the ADK runtime consumes it: a Tool
- * or a defineTool contract through toFunctionTool, an InstructionTool
- * through toAdkInstructionTool, a NativeToolMarker through toAdkNativeTool.
- * An ADK tool (one with runAsync) passes through as it is.
- */
-export function toAdkTool(tool) {
-    if (tool instanceof BaseTool || 'runAsync' in tool)
-        return tool;
-    if (isOwnToolset(tool))
-        throw new Error(`${tool.name ?? 'a toolset'} is a toolset: wrap it with toAdkToolset`);
-    if (isNativeToolMarker(tool))
-        return toAdkNativeTool(tool);
-    if (isInstructionTool(tool))
-        return toAdkInstructionTool(tool);
-    return toFunctionTool(tool);
-}

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

@@ -1,56 +0,0 @@
-/**
- * lib/tools/collectionsSearchTool.ts — xAI Collections search, sentinel-style.
- *
- * WHY this file exists:
- *   xAI's Agent Tools API can search "Collections" — hosted document stores
- *   (PDFs, text, CSVs) uploaded at console.x.ai or via the management API —
- *   semantic RAG run SERVER-SIDE, with citations back to source files
- *   (collections://<collection_id>/files/<file_id>). Declaring
- *   `collections_search` in an agent's YAML tools list turns it on for
- *   grok-* agents; xAI decides retrieval, we never ship documents in the
- *   prompt.
- *
- * HOW IT WORKS (mirrors xSearchTool.ts exactly):
- *   The sentinel self-registers in llmRequest.toolsDict; _getDeclaration()
- *   returns undefined so it is never sent as a client-side function tool.
- *   The GptLlm/GrokLlm request builder calls wantsCollectionsSearch() and
- *   appends the OpenAI-compatible wire shape:
- *     { type: 'file_search', vector_store_ids: [...], max_num_results? }
- *
- * WHICH COLLECTIONS: ids come from the environment, not YAML —
- *   XAI_COLLECTION_IDS (comma-separated) names the collections, and
- *   XAI_COLLECTIONS_MAX_RESULTS optionally caps retrieved chunks. Ids are
- *   deployment configuration (they differ per account/stage), which is
- *   what .env is for; the YAML stays shareable. Declared with no ids
- *   configured, the tool is omitted with a warning — never fatal.
- *
- * SCOPE: xAI-only. OpenAI's Responses API shares the file_search wire
- *   shape but searches OPENAI vector stores — a different product with
- *   different ids — so this sentinel gates to grok-* models and is a
- *   silent no-op everywhere else (same non-throwing routing contract as
- *   web_search / x_search).
- */
-import { BaseTool } from '../adkPeer.ts';
-import type { LlmRequest } from '@google/adk';
-import { NATIVE_TOOL } from './tool.ts';
-export declare const COLLECTIONS_SEARCH_TOOL_NAME = "collections_search";
-/** The ADK runtime's form of COLLECTIONS_SEARCH_MARKER (lib/tools/nativeTools.ts), carrying its marker. */
-export declare class CollectionsSearchTool extends BaseTool {
-    readonly [NATIVE_TOOL]: import("../model.ts").NativeTool;
-    constructor();
-    /** Never a client-side function tool — xAI runs retrieval server-side. */
-    _getDeclaration(): undefined;
-    /** Server-side tool: nothing to execute locally. */
-    runAsync(): Promise<unknown>;
-    processLlmRequest({ llmRequest }: {
-        llmRequest: LlmRequest;
-    }): Promise<void>;
-}
-/** Shared instance, mirroring WEB_SEARCH / X_SEARCH. */
-export declare const COLLECTIONS_SEARCH: CollectionsSearchTool;
-/** True when the agent requested collections search (xAI sentinel path), by marker. */
-export declare function wantsCollectionsSearch(llmRequest: LlmRequest): boolean;
-/** Sentinel test used by the request builder to skip function-tool emission: the collections_search marker, on either form. */
-export declare function isCollectionsSearchSentinel(tool: unknown): boolean;
-/** The XAI_COLLECTION* readers live in lib/tools/xaiSearchParams.ts (no @google/adk); re-exported here under their old names. */
-export { collectionIdsFromEnv, collectionsMaxResultsFromEnv } from './xaiSearchParams.ts';

package/dist/lib/tools/collectionsSearchTool.js

@@ -1,71 +0,0 @@
-/**
- * lib/tools/collectionsSearchTool.ts — xAI Collections search, sentinel-style.
- *
- * WHY this file exists:
- *   xAI's Agent Tools API can search "Collections" — hosted document stores
- *   (PDFs, text, CSVs) uploaded at console.x.ai or via the management API —
- *   semantic RAG run SERVER-SIDE, with citations back to source files
- *   (collections://<collection_id>/files/<file_id>). Declaring
- *   `collections_search` in an agent's YAML tools list turns it on for
- *   grok-* agents; xAI decides retrieval, we never ship documents in the
- *   prompt.
- *
- * HOW IT WORKS (mirrors xSearchTool.ts exactly):
- *   The sentinel self-registers in llmRequest.toolsDict; _getDeclaration()
- *   returns undefined so it is never sent as a client-side function tool.
- *   The GptLlm/GrokLlm request builder calls wantsCollectionsSearch() and
- *   appends the OpenAI-compatible wire shape:
- *     { type: 'file_search', vector_store_ids: [...], max_num_results? }
- *
- * WHICH COLLECTIONS: ids come from the environment, not YAML —
- *   XAI_COLLECTION_IDS (comma-separated) names the collections, and
- *   XAI_COLLECTIONS_MAX_RESULTS optionally caps retrieved chunks. Ids are
- *   deployment configuration (they differ per account/stage), which is
- *   what .env is for; the YAML stays shareable. Declared with no ids
- *   configured, the tool is omitted with a warning — never fatal.
- *
- * SCOPE: xAI-only. OpenAI's Responses API shares the file_search wire
- *   shape but searches OPENAI vector stores — a different product with
- *   different ids — so this sentinel gates to grok-* models and is a
- *   silent no-op everywhere else (same non-throwing routing contract as
- *   web_search / x_search).
- */
-import { BaseTool } from '../adkPeer.js';
-import { providerForModel } from '../models/providerMap.js';
-import { COLLECTIONS_SEARCH_MARKER } from './nativeTools.js';
-import { NATIVE_TOOL, nativeToolMarkerOf } from './tool.js';
-export const COLLECTIONS_SEARCH_TOOL_NAME = 'collections_search';
-/** The ADK runtime's form of COLLECTIONS_SEARCH_MARKER (lib/tools/nativeTools.ts), carrying its marker. */
-export class CollectionsSearchTool extends BaseTool {
-    [NATIVE_TOOL] = COLLECTIONS_SEARCH_MARKER[NATIVE_TOOL];
-    constructor() {
-        super({ name: COLLECTIONS_SEARCH_TOOL_NAME, description: COLLECTIONS_SEARCH_MARKER.description });
-    }
-    /** Never a client-side function tool — xAI runs retrieval server-side. */
-    _getDeclaration() {
-        return undefined;
-    }
-    /** Server-side tool: nothing to execute locally. */
-    async runAsync() {
-        return Promise.resolve();
-    }
-    async processLlmRequest({ llmRequest }) {
-        if (!llmRequest.model)
-            return;
-        if (providerForModel(llmRequest.model) !== 'xai')
-            return; // no-op elsewhere
-        llmRequest.toolsDict[COLLECTIONS_SEARCH_TOOL_NAME] = this;
-    }
-}
-/** Shared instance, mirroring WEB_SEARCH / X_SEARCH. */
-export const COLLECTIONS_SEARCH = new CollectionsSearchTool();
-/** True when the agent requested collections search (xAI sentinel path), by marker. */
-export function wantsCollectionsSearch(llmRequest) {
-    return isCollectionsSearchSentinel(llmRequest.toolsDict?.[COLLECTIONS_SEARCH_TOOL_NAME]);
-}
-/** Sentinel test used by the request builder to skip function-tool emission: the collections_search marker, on either form. */
-export function isCollectionsSearchSentinel(tool) {
-    return nativeToolMarkerOf(tool) === 'collections_search';
-}
-/** The XAI_COLLECTION* readers live in lib/tools/xaiSearchParams.ts (no @google/adk); re-exported here under their old names. */
-export { collectionIdsFromEnv, collectionsMaxResultsFromEnv } from './xaiSearchParams.js';

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

@@ -1,32 +0,0 @@
-/**
- * lib/tools/urlContextTool.ts — `url_context`: the model reads the pages
- * whose URLs appear in the conversation, server-side, on Gemini.
- *
- * WHY: ADK's URL_CONTEXT is Gemini's built-in URL reading, and it THROWS for
- * any other model, which would fail a mixed-provider syndicate at request
- * time. This is the same tool made safe to declare anywhere, the pattern
- * web_search uses: on a Gemini model it adds `{ urlContext: {} }` to the
- * request; on any other it does nothing, and `npm run doctor` reports it as
- * dropped (lib/models/capabilities.ts). For reading a page on every
- * provider, declare `web_extract` (client-side, SSRF-guarded).
- *
- * Exposure: Google fetches the URLs, not this host, so no address of this
- * deployment's network is reachable through it. Page text arrives as model
- * input; treat it as data, as any fetched page.
- */
-import { BaseTool } from '../adkPeer.ts';
-import type { LlmRequest } from '@google/adk';
-import { NATIVE_TOOL } from './tool.ts';
-export declare const URL_CONTEXT_TOOL_NAME = "url_context";
-/** The ADK runtime's form of URL_CONTEXT_MARKER (lib/tools/nativeTools.ts), carrying its marker. */
-export declare class UrlContextTool extends BaseTool {
-    readonly [NATIVE_TOOL]: import("../model.ts").NativeTool;
-    constructor();
-    /** Never a client-side function tool. */
-    _getDeclaration(): undefined;
-    runAsync(): Promise<unknown>;
-    processLlmRequest({ llmRequest }: {
-        llmRequest: LlmRequest;
-    }): Promise<void>;
-}
-export declare const URL_CONTEXT: UrlContextTool;

package/dist/lib/tools/urlContextTool.js

@@ -1,43 +0,0 @@
-/**
- * lib/tools/urlContextTool.ts — `url_context`: the model reads the pages
- * whose URLs appear in the conversation, server-side, on Gemini.
- *
- * WHY: ADK's URL_CONTEXT is Gemini's built-in URL reading, and it THROWS for
- * any other model, which would fail a mixed-provider syndicate at request
- * time. This is the same tool made safe to declare anywhere, the pattern
- * web_search uses: on a Gemini model it adds `{ urlContext: {} }` to the
- * request; on any other it does nothing, and `npm run doctor` reports it as
- * dropped (lib/models/capabilities.ts). For reading a page on every
- * provider, declare `web_extract` (client-side, SSRF-guarded).
- *
- * Exposure: Google fetches the URLs, not this host, so no address of this
- * deployment's network is reachable through it. Page text arrives as model
- * input; treat it as data, as any fetched page.
- */
-import { BaseTool } from '../adkPeer.js';
-import { providerForModel } from '../models/providerMap.js';
-import { URL_CONTEXT_MARKER } from './nativeTools.js';
-import { NATIVE_TOOL } from './tool.js';
-export const URL_CONTEXT_TOOL_NAME = 'url_context';
-/** The ADK runtime's form of URL_CONTEXT_MARKER (lib/tools/nativeTools.ts), carrying its marker. */
-export class UrlContextTool extends BaseTool {
-    [NATIVE_TOOL] = URL_CONTEXT_MARKER[NATIVE_TOOL];
-    constructor() {
-        super({ name: URL_CONTEXT_TOOL_NAME, description: URL_CONTEXT_MARKER.description });
-    }
-    /** Never a client-side function tool. */
-    _getDeclaration() {
-        return undefined;
-    }
-    async runAsync() {
-        return Promise.resolve();
-    }
-    async processLlmRequest({ llmRequest }) {
-        if (!llmRequest.model || providerForModel(llmRequest.model) !== 'gemini')
-            return;
-        llmRequest.config = llmRequest.config ?? {};
-        llmRequest.config.tools = llmRequest.config.tools ?? [];
-        llmRequest.config.tools.push({ urlContext: {} });
-    }
-}
-export const URL_CONTEXT = new UrlContextTool();

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

@@ -1,51 +0,0 @@
-/**
- * lib/tools/webSearchTool.ts — provider-agnostic web search.
- *
- * WHY this file exists:
- *   ADK's built-in GOOGLE_SEARCH tool is Gemini grounding — it THROWS for any
- *   non-Gemini model. But every cloud provider this framework routes to has
- *   its own native web search: Gemini grounding, Anthropic's web_search
- *   server tool, OpenAI's Responses web_search tool, xAI's web_search server
- *   tool.
- *   Declaring `web_search` in an agent's YAML tools list routes to whichever
- *   of those the agent's model supports — the YAML stays model-agnostic.
- *
- * HOW IT WORKS:
- *   ADK calls processLlmRequest() on every tool while building the request,
- *   with llmRequest.model already set (LlmAgent resolves the model first).
- *   - Gemini model  → push { googleSearch: {} } into config.tools, exactly
- *     what ADK's own GoogleSearchTool does for Gemini 2+.
- *   - Anything else → self-register in llmRequest.toolsDict as a sentinel.
- *     _getDeclaration() returns undefined, so the sentinel is never sent as
- *     a client-side function tool; each provider adapter calls
- *     wantsWebSearch(llmRequest) and enables its provider's NATIVE search
- *     (Claude: web_search server tool; GPT: Responses web_search; Grok:
- *     Agent Tools web_search). Models with no native search (local Ollama) omit
- *     the tool and warn — local mode stays keyless by design.
- *
- *   `google_search` remains available as the Gemini-only ADK tool for
- *   backward compatibility; new YAMLs should declare `web_search`.
- */
-import { BaseTool } from '../adkPeer.ts';
-import type { LlmRequest } from '@google/adk';
-import { NATIVE_TOOL } from './tool.ts';
-export declare const WEB_SEARCH_TOOL_NAME = "web_search";
-/** The ADK runtime's form of WEB_SEARCH_MARKER (lib/tools/nativeTools.ts), carrying its marker. */
-export declare class WebSearchTool extends BaseTool {
-    readonly [NATIVE_TOOL]: import("../model.ts").NativeTool;
-    constructor();
-    /** Never a client-side function tool — providers run search server-side. */
-    _getDeclaration(): undefined;
-    /** Server-side tool: nothing to execute locally. */
-    runAsync(): Promise<unknown>;
-    processLlmRequest({ llmRequest }: {
-        llmRequest: LlmRequest;
-    }): Promise<void>;
-}
-/** Shared instance, mirroring ADK's GOOGLE_SEARCH constant pattern. */
-export declare const WEB_SEARCH: WebSearchTool;
-/** True when the agent requested web search (non-Gemini sentinel path), by marker. */
-export declare function wantsWebSearch(llmRequest: LlmRequest): boolean;
-/** True for toolsDict entries adapters must NOT send as function tools: the web_search marker, on either form. */
-export declare function isWebSearchSentinel(tool: unknown): boolean;
-export { xaiWebSearchParamsFromEnv } from './xaiSearchParams.ts';

package/dist/lib/tools/webSearchTool.js

@@ -1,82 +0,0 @@
-/**
- * lib/tools/webSearchTool.ts — provider-agnostic web search.
- *
- * WHY this file exists:
- *   ADK's built-in GOOGLE_SEARCH tool is Gemini grounding — it THROWS for any
- *   non-Gemini model. But every cloud provider this framework routes to has
- *   its own native web search: Gemini grounding, Anthropic's web_search
- *   server tool, OpenAI's Responses web_search tool, xAI's web_search server
- *   tool.
- *   Declaring `web_search` in an agent's YAML tools list routes to whichever
- *   of those the agent's model supports — the YAML stays model-agnostic.
- *
- * HOW IT WORKS:
- *   ADK calls processLlmRequest() on every tool while building the request,
- *   with llmRequest.model already set (LlmAgent resolves the model first).
- *   - Gemini model  → push { googleSearch: {} } into config.tools, exactly
- *     what ADK's own GoogleSearchTool does for Gemini 2+.
- *   - Anything else → self-register in llmRequest.toolsDict as a sentinel.
- *     _getDeclaration() returns undefined, so the sentinel is never sent as
- *     a client-side function tool; each provider adapter calls
- *     wantsWebSearch(llmRequest) and enables its provider's NATIVE search
- *     (Claude: web_search server tool; GPT: Responses web_search; Grok:
- *     Agent Tools web_search). Models with no native search (local Ollama) omit
- *     the tool and warn — local mode stays keyless by design.
- *
- *   `google_search` remains available as the Gemini-only ADK tool for
- *   backward compatibility; new YAMLs should declare `web_search`.
- */
-import { BaseTool } from '../adkPeer.js';
-import { providerForModel } from '../models/providerMap.js';
-import { WEB_SEARCH_MARKER } from './nativeTools.js';
-import { NATIVE_TOOL, nativeToolMarkerOf } from './tool.js';
-export const WEB_SEARCH_TOOL_NAME = 'web_search';
-/** The ADK runtime's form of WEB_SEARCH_MARKER (lib/tools/nativeTools.ts), carrying its marker. */
-export class WebSearchTool extends BaseTool {
-    [NATIVE_TOOL] = WEB_SEARCH_MARKER[NATIVE_TOOL];
-    constructor() {
-        super({ name: WEB_SEARCH_TOOL_NAME, description: WEB_SEARCH_MARKER.description });
-    }
-    /** Never a client-side function tool — providers run search server-side. */
-    _getDeclaration() {
-        return undefined;
-    }
-    /** Server-side tool: nothing to execute locally. */
-    async runAsync() {
-        return Promise.resolve();
-    }
-    async processLlmRequest({ llmRequest }) {
-        if (!llmRequest.model)
-            return;
-        if (providerForModel(llmRequest.model) === 'gemini') {
-            // Native Gemini grounding — same wire shape ADK's GoogleSearchTool
-            // emits for Gemini 2+ (we can't reuse that class: it throws for
-            // non-Gemini models, and this tool must never throw on routing).
-            llmRequest.config = llmRequest.config ?? {};
-            llmRequest.config.tools = llmRequest.config.tools ?? [];
-            llmRequest.config.tools.push({ googleSearch: {} });
-            return;
-        }
-        // Non-Gemini: leave a sentinel for the provider adapter. Safe because
-        // _getDeclaration() is undefined — ADK's appendTools never adds this
-        // to the function-tool declarations sent to the model.
-        llmRequest.toolsDict[WEB_SEARCH_TOOL_NAME] = this;
-    }
-}
-/** Shared instance, mirroring ADK's GOOGLE_SEARCH constant pattern. */
-export const WEB_SEARCH = new WebSearchTool();
-/** True when the agent requested web search (non-Gemini sentinel path), by marker. */
-export function wantsWebSearch(llmRequest) {
-    return isWebSearchSentinel(llmRequest.toolsDict?.[WEB_SEARCH_TOOL_NAME]);
-}
-/** True for toolsDict entries adapters must NOT send as function tools: the web_search marker, on either form. */
-export function isWebSearchSentinel(tool) {
-    return nativeToolMarkerOf(tool) === 'web_search';
-}
-// ── xAI-only server-side constraints ─────────────────────────────────────────
-//
-// xAI's web_search domain filters (XAI_WEB_SEARCH_ALLOWED_DOMAINS /
-// XAI_WEB_SEARCH_EXCLUDED_DOMAINS) are read in lib/tools/xaiSearchParams.ts,
-// which imports nothing, so GrokAdapter reaches no @google/adk. Re-exported
-// here under the old name.
-export { xaiWebSearchParamsFromEnv } from './xaiSearchParams.js';

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

@@ -1,59 +0,0 @@
-/**
- * lib/tools/xSearchTool.ts — xAI X (Twitter) search, sentinel-style.
- *
- * WHY this file exists:
- *   xAI's Agent Tools API exposes `x_search` — server-side live search over
- *   X posts — as a first-class tool alongside `web_search` (verified live
- *   against api.x.ai/v1/responses, 2026-07-24). It is the one search
- *   capability no other provider offers, and the reason to route a
- *   news/social agent to a grok-* model at all.
- *
- * HOW IT WORKS (mirrors webSearchTool.ts exactly):
- *   Declaring `x_search` in an agent's YAML tools list self-registers a
- *   sentinel in llmRequest.toolsDict. _getDeclaration() returns undefined so
- *   it is never sent as a client-side function tool; the GptLlm/GrokLlm
- *   request builder calls wantsXSearch(llmRequest) and appends
- *   { type: 'x_search' } to the provider tools.
- *
- * SCOPE: xAI-only. Declare it ONLY on grok-* agents — other Responses-API
- *   providers (OpenAI) reject the unknown tool type with a 400, and Gemini/
- *   Anthropic adapters ignore the sentinel entirely (the tool degrades to a
- *   no-op there rather than throwing, same non-throwing routing contract as
- *   web_search).
- *
- * WHICH CONSTRAINTS: xAI accepts server-side search constraints on the tool
- *   object itself (verified against docs.x.ai/developers/tools/x-search,
- *   2026-08-02): from_date/to_date (YYYY-MM-DD) and allowed_x_handles/
- *   excluded_x_handles (≤20 each, mutually exclusive). They come from the
- *   environment, not YAML — XAI_X_SEARCH_FROM_DATE, XAI_X_SEARCH_TO_DATE,
- *   XAI_X_SEARCH_ALLOWED_HANDLES, XAI_X_SEARCH_EXCLUDED_HANDLES (handle
- *   lists comma-separated, leading @ tolerated) — the XAI_COLLECTION_IDS
- *   doctrine: constraints are deployment configuration, the YAML stays
- *   shareable. Misconfiguration degrades with a warning, never fatally:
- *   malformed dates are dropped, oversize handle lists truncate, and when
- *   both lists are set the allowlist wins.
- */
-import { BaseTool } from '../adkPeer.ts';
-import type { LlmRequest } from '@google/adk';
-import { NATIVE_TOOL } from './tool.ts';
-export declare const X_SEARCH_TOOL_NAME = "x_search";
-/** The ADK runtime's form of X_SEARCH_MARKER (lib/tools/nativeTools.ts), carrying its marker. */
-export declare class XSearchTool extends BaseTool {
-    readonly [NATIVE_TOOL]: import("../model.ts").NativeTool;
-    constructor();
-    /** Never a client-side function tool — xAI runs the search server-side. */
-    _getDeclaration(): undefined;
-    /** Server-side tool: nothing to execute locally. */
-    runAsync(): Promise<unknown>;
-    processLlmRequest({ llmRequest }: {
-        llmRequest: LlmRequest;
-    }): Promise<void>;
-}
-/** Shared instance, mirroring WEB_SEARCH. */
-export declare const X_SEARCH: XSearchTool;
-/** True when the agent requested X search (xAI sentinel path), by marker. */
-export declare function wantsXSearch(llmRequest: LlmRequest): boolean;
-/** Sentinel test used by the request builder to skip function-tool emission: the x_search marker, on either form. */
-export declare function isXSearchSentinel(tool: unknown): boolean;
-/** The XAI_X_SEARCH_* reader lives in lib/tools/xaiSearchParams.ts (no @google/adk); re-exported here under its old name. */
-export { xSearchParamsFromEnv } from './xaiSearchParams.ts';