melchizedek-agents 0.18.0 → 0.19.0

package/dist/lib/models/schemaNormalize.d.ts

@@ -12,7 +12,27 @@
  *   Tools are declared once (YAML / MCP discovery) in the Gemini dialect, so
  *   every non-Gemini adapter runs its tool schemas through this function at
  *   request-build time. See DOCUMENTATION.md §7.1.
+ *
+ *   The engine's own model contract (lib/models/contract.ts, ADR 0048) takes
+ *   tools in its own shape instead: contractToolDeclaration() builds a
+ *   ToolDeclaration from an own Tool (lib/tools/tool.ts), an ADK tool or a
+ *   defineTool contract, converting Gemini's dialect once, where the tool
+ *   enters, and nativeToolOf() names the server-side tools that declare
+ *   nothing. The functions above stay as they are for the ADK path's adapters.
+ *
+ *   zodInputJsonSchema() is the one place a zod schema becomes JSON Schema,
+ *   for every surface: the declaration, the ADK FunctionTool and the MCP
+ *   tools/list entry all derive from it.
+ */
+import { z } from 'zod';
+import type { JsonSchema, NativeTool, ToolDeclaration } from './contract.ts';
+/**
+ * Standard JSON Schema for what a caller may send a zod schema: its input
+ * side (`io: 'input'`), so a field with a default is optional to the model,
+ * as it is to the schema. `$schema` is dropped: it is metadata about the
+ * document, noise on the wire.
  */
+export declare function zodInputJsonSchema(schema: z.ZodType): Record<string, unknown>;
 /**
  * Deep-clones a Gemini/ADK-style JSON schema, lowercasing every `type` value
  * ('OBJECT' → 'object', ['STRING','NULL'] → ['string','null']) while leaving
@@ -49,3 +69,81 @@ export declare function toolDeclarationFor(tool: unknown): {
  * names the harness expects rather than improvised ones.
  */
 export declare function toStrictJsonSchema(schema: unknown): Record<string, unknown>;
+/**
+ * A deep copy of `schema` with `visit` applied to every schema node of the
+ * copy, children first, following only the keywords that hold schemas (a
+ * property named `default` or `additionalProperties` is a property, not the
+ * keyword). Never mutates `schema`. Undefined for a schema that is not an
+ * object.
+ */
+export declare function mapSchemaNodes(schema: unknown, visit: (node: Record<string, unknown>) => void): Record<string, unknown> | undefined;
+/**
+ * A copy of `schema` as lowercase JSON Schema, the contract's one dialect
+ * (`JsonSchema`), from either dialect. With `strict`, every object node
+ * that has properties, at any depth (inside `items`, `anyOf`, `$defs`, …),
+ * lists all of them as required and sets `additionalProperties: false`: the
+ * form OpenAI's and Anthropic's strict modes demand. An object without
+ * properties (a map) is left open, so a strict provider refuses it instead
+ * of receiving a field the model can never fill. Never mutates `schema`.
+ */
+export declare function toContractJsonSchema(schema: unknown, options?: {
+    strict?: boolean;
+}): JsonSchema;
+/**
+ * The parameters a zod schema declares, in the contract's dialect: its
+ * input side (zodInputJsonSchema) without the keywords the ADK path cannot
+ * carry (dropZodOnlyKeywords). defineTool's declaration() and
+ * contractToolDeclaration() both build from here, so a contract declares the
+ * same parameters on either runtime.
+ */
+export declare function zodToolParameters(schema: z.ZodType, options?: {
+    strict?: boolean;
+}): JsonSchema;
+/**
+ * The declaration a model receives for one client-side tool, in the
+ * contract's shape (ToolDeclaration, lib/models/contract.ts).
+ *
+ * - An own Tool (lib/tools/tool.ts), defineTool's among them: its own
+ *   `declaration()`.
+ * - A plain defineTool-shaped contract (name, description, zod schema,
+ *   execute): built directly from its zod schema (zodToolParameters), never
+ *   through Gemini's uppercase dialect. The input side is declared, so a
+ *   field with a default is optional; the `default` keyword and a boolean
+ *   `additionalProperties` are left out, as the ADK path leaves them out,
+ *   and a record's value schema is kept, as the ADK path keeps it. The
+ *   contract and the FunctionTool that toFunctionTool() makes of it declare
+ *   the same parameters.
+ * - An ADK tool (FunctionTool, AgentTool, the memory tools, MCP tools): read
+ *   from its own `_getDeclaration()` (ADR 0019), `parameters` or else
+ *   `parametersJsonSchema`, and converted from Gemini's dialect once, here.
+ * - A plain object with `name` and `parameters` (tests, hand-built tools).
+ *
+ * With `strict`, the parameters take the strict form (toContractJsonSchema)
+ * and the declaration carries `strict: true`. Returns undefined for a tool
+ * that declares nothing (a server-side tool: see nativeToolOf, or an
+ * InstructionTool such as `preload_memory`, which only writes into the
+ * instruction, as itself or as its ADK tool) and for one with no name.
+ */
+export declare function contractToolDeclaration(tool: unknown, options?: {
+    strict?: boolean;
+}): ToolDeclaration | undefined;
+/**
+ * The NativeTool a tool object stands for, or undefined for any other tool.
+ * Recognised by marker, never by class or by shape, and every marker lives
+ * in the global symbol registry, so a second copy of a module (or of ADK)
+ * still matches (ADR 0062):
+ *   - the engine's own marker (lib/tools/tool.ts, NATIVE_TOOL): a
+ *     NativeToolMarker (lib/tools/nativeTools.ts) and the ADK sentinel made
+ *     from it (lib/tools/webSearchTool.ts and its siblings);
+ *   - Gemini code execution: ADK's built-in code executor, by ADK's marker
+ *     (the agent's `codeExecutor`, from `code_execution: gemini`);
+ *   - ADK's own GOOGLE_SEARCH and URL_CONTEXT, by ADK's marker for a tool
+ *     the model runs, and their name.
+ * A client-side tool registered under one of those names carries no marker,
+ * so it stays a client-side tool, as does a tool that merely declares
+ * nothing. ADK's other in-model tools (Vertex AI Search, enterprise web
+ * search, Maps grounding, RAG retrieval) have no NativeTool: they are
+ * undefined here and declare nothing, so a caller building a request
+ * reports them as dropped.
+ */
+export declare function nativeToolOf(tool: unknown): NativeTool | undefined;

package/dist/lib/models/schemaNormalize.js

@@ -12,7 +12,38 @@
  *   Tools are declared once (YAML / MCP discovery) in the Gemini dialect, so
  *   every non-Gemini adapter runs its tool schemas through this function at
  *   request-build time. See DOCUMENTATION.md §7.1.
+ *
+ *   The engine's own model contract (lib/models/contract.ts, ADR 0048) takes
+ *   tools in its own shape instead: contractToolDeclaration() builds a
+ *   ToolDeclaration from an own Tool (lib/tools/tool.ts), an ADK tool or a
+ *   defineTool contract, converting Gemini's dialect once, where the tool
+ *   enters, and nativeToolOf() names the server-side tools that declare
+ *   nothing. The functions above stay as they are for the ADK path's adapters.
+ *
+ *   zodInputJsonSchema() is the one place a zod schema becomes JSON Schema,
+ *   for every surface: the declaration, the ADK FunctionTool and the MCP
+ *   tools/list entry all derive from it.
  */
+import { z } from 'zod';
+import { isInstructionTool, isTool, nativeToolMarkerOf } from '../tools/tool.js';
+/**
+ * Standard JSON Schema for what a caller may send a zod schema: its input
+ * side (`io: 'input'`), so a field with a default is optional to the model,
+ * as it is to the schema. `$schema` is dropped: it is metadata about the
+ * document, noise on the wire.
+ */
+export function zodInputJsonSchema(schema) {
+    const { $schema: _drop, ...json } = z.toJSONSchema(schema, { io: 'input' });
+    // A record's `propertyNames: { type: 'string' }` says only that its keys
+    // are strings, which JSON keys always are. Gemini refuses the keyword
+    // with a 400 (live, 2026-10-08), so it is left out here, the one source
+    // every path reads, and the paths keep declaring the same parameters.
+    return mapSchemaNodes(json, (node) => {
+        const names = node.propertyNames;
+        if (isPlainObject(names) && Object.keys(names).length === 1 && names.type === 'string')
+            delete node.propertyNames;
+    }) ?? json;
+}
 /**
  * Deep-clones a Gemini/ADK-style JSON schema, lowercasing every `type` value
  * ('OBJECT' → 'object', ['STRING','NULL'] → ['string','null']) while leaving
@@ -72,7 +103,7 @@ function normalizeNode(node) {
  * search sentinels) and for tools with no name.
  */
 export function toolDeclarationFor(tool) {
-    if (!tool || typeof tool !== 'object')
+    if (!tool || typeof tool !== 'object' || nativeToolMarkerOf(tool))
         return undefined;
     const t = tool;
     let decl;
@@ -133,3 +164,292 @@ function strictNode(node) {
 function isPlainObject(v) {
     return !!v && typeof v === 'object' && !Array.isArray(v);
 }
+// ── Tool declarations in the contract's shape (ADR 0048) ─────────────────────
+/** Keywords whose value is one schema (`items` may also be a draft-4 tuple of them). */
+const SUBSCHEMA_KEYWORDS = new Set([
+    'items', 'additionalItems', 'additionalProperties', 'unevaluatedItems', 'unevaluatedProperties',
+    'contains', 'propertyNames', 'not', 'if', 'then', 'else',
+]);
+/** Keywords whose value is a list of schemas. */
+const SUBSCHEMA_LIST_KEYWORDS = new Set(['anyOf', 'oneOf', 'allOf', 'prefixItems']);
+/** Keywords whose value maps names to schemas. */
+const SUBSCHEMA_MAP_KEYWORDS = new Set(['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas']);
+/** Bounds Gemini's Schema spells as int64 strings (`'1'`); JSON Schema wants integers. */
+const INTEGER_KEYWORDS = ['minLength', 'maxLength', 'minItems', 'maxItems', 'minProperties', 'maxProperties'];
+/**
+ * What a declaration built from a zod schema leaves out, as the ADK path
+ * (toGeminiSchema) leaves it out, so a contract declares the same
+ * parameters whichever path resolves it: the `default` keyword (zod applies
+ * defaults at parse time, and the field is already optional), and an
+ * `additionalProperties` that is only `true` or `false`. An
+ * `additionalProperties` holding a schema, a record's value schema, is kept.
+ */
+function dropZodOnlyKeywords(node) {
+    delete node.default;
+    if (typeof node.additionalProperties === 'boolean')
+        delete node.additionalProperties;
+}
+/** ADK's built-ins that a model runs itself, by the NativeTool their name is. */
+const ADK_IN_MODEL_NATIVE_TOOLS = ['google_search', 'url_context'];
+/**
+ * ADK's markers, read through the global symbol registry so this module
+ * imports nothing from ADK: a tool the model runs itself (GOOGLE_SEARCH,
+ * ADK's URL_CONTEXT) and Gemini's built-in code executor.
+ */
+const ADK_IN_MODEL_TOOL = Symbol.for('google.adk.inModelTool');
+const ADK_BUILT_IN_CODE_EXECUTOR = Symbol.for('google.adk.builtInCodeExecutor');
+/** A deep copy of a JSON value, so a walk can change it without touching a tool's own schema. */
+function cloneJson(value) {
+    if (Array.isArray(value))
+        return value.map(cloneJson);
+    if (isPlainObject(value))
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, cloneJson(v)]));
+    return value;
+}
+/**
+ * Visits every schema node in place, children first. It follows only the
+ * keywords that hold schemas, so a property named `type`, `enum` or
+ * `default` is a property like any other, and data (`enum`, `const`,
+ * `default`, `examples`) is never read as a schema.
+ */
+function walkSchema(node, visit) {
+    if (!isPlainObject(node))
+        return; // boolean schemas, malformed nodes
+    for (const [key, value] of Object.entries(node)) {
+        if (SUBSCHEMA_KEYWORDS.has(key)) {
+            if (Array.isArray(value))
+                value.forEach((v) => walkSchema(v, visit));
+            else
+                walkSchema(value, visit);
+        }
+        else if (SUBSCHEMA_LIST_KEYWORDS.has(key) && Array.isArray(value)) {
+            value.forEach((v) => walkSchema(v, visit));
+        }
+        else if (SUBSCHEMA_MAP_KEYWORDS.has(key) && isPlainObject(value)) {
+            Object.values(value).forEach((v) => walkSchema(v, visit));
+        }
+    }
+    visit(node);
+}
+/**
+ * A deep copy of `schema` with `visit` applied to every schema node of the
+ * copy, children first, following only the keywords that hold schemas (a
+ * property named `default` or `additionalProperties` is a property, not the
+ * keyword). Never mutates `schema`. Undefined for a schema that is not an
+ * object.
+ */
+export function mapSchemaNodes(schema, visit) {
+    if (!isPlainObject(schema))
+        return undefined;
+    const root = cloneJson(schema);
+    walkSchema(root, visit);
+    return root;
+}
+/** Keywords that say what a node is about, not what it admits; they stay put when a nullable node is wrapped. */
+const ANNOTATION_KEYWORDS = new Set(['title', 'description', 'default', 'examples', '$comment', 'deprecated', 'readOnly', 'writeOnly', '$defs', 'definitions']);
+/** Keywords beside which a type that admits null still refuses it. */
+const NULL_REFUSING_KEYWORDS = ['allOf', 'anyOf', 'oneOf', '$ref', 'not', 'const'];
+/**
+ * One node from Gemini's dialect into lowercase JSON Schema: types
+ * lowercased, int64 bounds as integers, the strict form when asked, and
+ * OpenAPI's `nullable: true` turned into a schema that admits null. Strict
+ * comes before null, because admitting null may move the node's properties
+ * into an anyOf branch the walk has already passed. A node already in the
+ * standard dialect passes through unchanged.
+ */
+function toContractNode(node, fromZod, strict) {
+    delete node.$schema;
+    if (fromZod)
+        dropZodOnlyKeywords(node);
+    if (typeof node.type === 'string')
+        node.type = node.type.toLowerCase();
+    else if (Array.isArray(node.type))
+        node.type = node.type.map((t) => (typeof t === 'string' ? t.toLowerCase() : t));
+    for (const key of INTEGER_KEYWORDS) {
+        const bound = node[key];
+        if (typeof bound === 'string' && /^\d+$/.test(bound))
+            node[key] = Number(bound);
+    }
+    if (strict)
+        toStrictNode(node);
+    if (typeof node.nullable !== 'boolean')
+        return;
+    const nullable = node.nullable;
+    delete node.nullable;
+    if (nullable)
+        admitNull(node);
+}
+/**
+ * Make `node` admit null. A plain typed node gains `null` in its type (and
+ * its enum, which would otherwise refuse it); a bare `anyOf` gains a null
+ * branch; anything else ($ref, allOf, oneOf, const…) moves into an anyOf
+ * beside `{ type: 'null' }`, its annotations staying on the node.
+ */
+function admitNull(node) {
+    const composed = NULL_REFUSING_KEYWORDS.some((k) => k in node);
+    if (node.type !== undefined && !composed) {
+        const types = Array.isArray(node.type) ? node.type : [node.type];
+        if (!types.includes('null'))
+            node.type = typeof node.type === 'string' ? [node.type, 'null'] : [...types, 'null'];
+        if (Array.isArray(node.enum) && !node.enum.includes(null))
+            node.enum = [...node.enum, null];
+        return;
+    }
+    const constraints = Object.keys(node).filter((k) => !ANNOTATION_KEYWORDS.has(k));
+    if (constraints.length === 0)
+        return; // an unconstrained schema admits null already
+    if (constraints.length === 1 && constraints[0] === 'anyOf' && Array.isArray(node.anyOf)) {
+        if (!node.anyOf.some((s) => isPlainObject(s) && s.type === 'null'))
+            node.anyOf = [...node.anyOf, { type: 'null' }];
+        return;
+    }
+    // fromEntries defines each key, so an own `__proto__` from an untrusted
+    // (MCP) schema stays a key instead of setting the new object's prototype.
+    const inner = Object.fromEntries(constraints.map((key) => [key, node[key]]));
+    for (const key of constraints)
+        delete node[key];
+    node.anyOf = [inner, { type: 'null' }];
+}
+/**
+ * The strict form of one node: an object with properties lists them all as
+ * required and allows no others. An optional property becomes required as
+ * it is, not widened to null: a contract's zod schema would refuse the null.
+ */
+function toStrictNode(node) {
+    if (!isPlainObject(node.properties))
+        return;
+    node.required = Object.keys(node.properties);
+    node.additionalProperties = false;
+}
+/**
+ * A copy of `schema` as lowercase JSON Schema, the contract's one dialect
+ * (`JsonSchema`), from either dialect. With `strict`, every object node
+ * that has properties, at any depth (inside `items`, `anyOf`, `$defs`, …),
+ * lists all of them as required and sets `additionalProperties: false`: the
+ * form OpenAI's and Anthropic's strict modes demand. An object without
+ * properties (a map) is left open, so a strict provider refuses it instead
+ * of receiving a field the model can never fill. Never mutates `schema`.
+ */
+export function toContractJsonSchema(schema, options = {}) {
+    return contractSchema(schema, false, options.strict === true);
+}
+/**
+ * The parameters a zod schema declares, in the contract's dialect: its
+ * input side (zodInputJsonSchema) without the keywords the ADK path cannot
+ * carry (dropZodOnlyKeywords). defineTool's declaration() and
+ * contractToolDeclaration() both build from here, so a contract declares the
+ * same parameters on either runtime.
+ */
+export function zodToolParameters(schema, options = {}) {
+    return contractSchema(zodInputJsonSchema(schema), true, options.strict === true);
+}
+function contractSchema(schema, fromZod, strict) {
+    return mapSchemaNodes(schema, (node) => toContractNode(node, fromZod, strict)) ?? { type: 'object', properties: {} };
+}
+/** A defineTool contract (lib/tools/toolContract.ts), told apart from an ADK tool, which has runAsync. */
+function isToolContract(tool) {
+    const schema = tool.schema;
+    return !!schema && typeof schema.safeParse === 'function' && typeof tool.execute === 'function' && !('runAsync' in tool);
+}
+/**
+ * The declaration a model receives for one client-side tool, in the
+ * contract's shape (ToolDeclaration, lib/models/contract.ts).
+ *
+ * - An own Tool (lib/tools/tool.ts), defineTool's among them: its own
+ *   `declaration()`.
+ * - A plain defineTool-shaped contract (name, description, zod schema,
+ *   execute): built directly from its zod schema (zodToolParameters), never
+ *   through Gemini's uppercase dialect. The input side is declared, so a
+ *   field with a default is optional; the `default` keyword and a boolean
+ *   `additionalProperties` are left out, as the ADK path leaves them out,
+ *   and a record's value schema is kept, as the ADK path keeps it. The
+ *   contract and the FunctionTool that toFunctionTool() makes of it declare
+ *   the same parameters.
+ * - An ADK tool (FunctionTool, AgentTool, the memory tools, MCP tools): read
+ *   from its own `_getDeclaration()` (ADR 0019), `parameters` or else
+ *   `parametersJsonSchema`, and converted from Gemini's dialect once, here.
+ * - A plain object with `name` and `parameters` (tests, hand-built tools).
+ *
+ * With `strict`, the parameters take the strict form (toContractJsonSchema)
+ * and the declaration carries `strict: true`. Returns undefined for a tool
+ * that declares nothing (a server-side tool: see nativeToolOf, or an
+ * InstructionTool such as `preload_memory`, which only writes into the
+ * instruction, as itself or as its ADK tool) and for one with no name.
+ */
+export function contractToolDeclaration(tool, options = {}) {
+    if (!isPlainObject(tool) || isInstructionTool(tool) || nativeToolMarkerOf(tool))
+        return undefined;
+    const strict = options.strict === true;
+    let name;
+    let description;
+    let parameters;
+    if (isTool(tool)) {
+        const decl = tool.declaration();
+        name = decl.name;
+        description = decl.description;
+        parameters = contractSchema(decl.parameters, false, strict);
+    }
+    else if (isToolContract(tool)) {
+        name = tool.name;
+        description = tool.description;
+        parameters = zodToolParameters(tool.schema, { strict });
+    }
+    else {
+        let decl;
+        if (typeof tool._getDeclaration === 'function') {
+            try {
+                decl = tool._getDeclaration() ?? undefined;
+            }
+            catch {
+                decl = undefined;
+            }
+            // A tool that implements _getDeclaration and returns nothing declares nothing.
+            if (!decl)
+                return undefined;
+        }
+        name = decl ? decl.name ?? tool.name : tool.name;
+        description = decl ? decl.description ?? tool.description : tool.description;
+        const declared = decl ? decl.parameters ?? decl.parametersJsonSchema : tool.parameters;
+        parameters = contractSchema(declared, false, strict);
+    }
+    if (!name || typeof name !== 'string')
+        return undefined;
+    return {
+        name,
+        description: typeof description === 'string' ? description : '',
+        parameters,
+        ...(strict ? { strict: true } : {}),
+    };
+}
+/**
+ * The NativeTool a tool object stands for, or undefined for any other tool.
+ * Recognised by marker, never by class or by shape, and every marker lives
+ * in the global symbol registry, so a second copy of a module (or of ADK)
+ * still matches (ADR 0062):
+ *   - the engine's own marker (lib/tools/tool.ts, NATIVE_TOOL): a
+ *     NativeToolMarker (lib/tools/nativeTools.ts) and the ADK sentinel made
+ *     from it (lib/tools/webSearchTool.ts and its siblings);
+ *   - Gemini code execution: ADK's built-in code executor, by ADK's marker
+ *     (the agent's `codeExecutor`, from `code_execution: gemini`);
+ *   - ADK's own GOOGLE_SEARCH and URL_CONTEXT, by ADK's marker for a tool
+ *     the model runs, and their name.
+ * A client-side tool registered under one of those names carries no marker,
+ * so it stays a client-side tool, as does a tool that merely declares
+ * nothing. ADK's other in-model tools (Vertex AI Search, enterprise web
+ * search, Maps grounding, RAG retrieval) have no NativeTool: they are
+ * undefined here and declare nothing, so a caller building a request
+ * reports them as dropped.
+ */
+export function nativeToolOf(tool) {
+    if (!tool || typeof tool !== 'object')
+        return undefined;
+    const own = nativeToolMarkerOf(tool);
+    if (own)
+        return own;
+    const t = tool;
+    if (t[ADK_BUILT_IN_CODE_EXECUTOR] === true)
+        return 'code_execution';
+    if (t[ADK_IN_MODEL_TOOL] !== true)
+        return undefined;
+    return ADK_IN_MODEL_NATIVE_TOOLS.find((n) => n === t.name);
+}

package/dist/lib/models/tracedGemini.d.ts

@@ -0,0 +1,41 @@
+/**
+ * lib/models/tracedGemini.ts — ADK's built-in Gemini, wrapped so Gemini calls
+ * emit the same per-request llm.request spans (tokens, latency) as every other
+ * provider, and get the shared transient-failure retries (lib/models/retry.ts).
+ *
+ * WHY its own module: two modules use it. lib/models/registry.ts registers it
+ * for every Gemini id on the ADK path and builds it in resolveModel, and the
+ * temporary AdkGeminiAdapter (lib/models/adkGeminiAdapter.ts) runs its calls
+ * through generateWithRetries. registry.ts also builds that adapter in
+ * resolveAdapter, so the class living in registry.ts would be an ESM import
+ * cycle. registry.ts re-exports it, so `TracedGemini` imports from there keep
+ * working.
+ */
+import { Gemini } from '@google/adk';
+import type { GeminiParams, LlmRequest, LlmResponse } from '@google/adk';
+import type { ProviderEndpoint } from './endpoints.ts';
+export declare class TracedGemini extends Gemini {
+    #private;
+    static readonly supportedModels: Array<string | RegExp>;
+    /**
+     * The Gemini platform (ADR 0023) applies to every construction, the
+     * LLMRegistry's included: on Vertex AI the client authenticates with
+     * Google Application Default Credentials for the configured project and
+     * location, and an AI Studio key (the environment's or a caller's) is not
+     * sent. `endpoint` overrides the environment's (the credentials plug point).
+     */
+    constructor(params?: GeminiParams & {
+        endpoint?: ProviderEndpoint;
+    });
+    generateContentAsync(llmRequest: LlmRequest, stream?: boolean, abortSignal?: AbortSignal): AsyncGenerator<LlmResponse, void>;
+    /**
+     * One call through ADK's Gemini with the shared retries, tagging whatever
+     * llm.request span is active (llm.web_search.native for Gemini grounding,
+     * llm.retries, llm.http_status). generateContentAsync opens that span
+     * around it; AdkGeminiAdapter (lib/models/adkGeminiAdapter.ts) runs it
+     * inside the span its own caller opens (ADR 0053). A failed call throws,
+     * as ADK's Gemini does. The abort signal is forwarded so a canceled turn stops the
+     * request in flight (ADK's Gemini puts it on the genai request config).
+     */
+    generateWithRetries(llmRequest: LlmRequest, stream?: boolean, abortSignal?: AbortSignal): AsyncGenerator<LlmResponse, void>;
+}

package/dist/lib/models/tracedGemini.js

@@ -0,0 +1,98 @@
+/**
+ * lib/models/tracedGemini.ts — ADK's built-in Gemini, wrapped so Gemini calls
+ * emit the same per-request llm.request spans (tokens, latency) as every other
+ * provider, and get the shared transient-failure retries (lib/models/retry.ts).
+ *
+ * WHY its own module: two modules use it. lib/models/registry.ts registers it
+ * for every Gemini id on the ADK path and builds it in resolveModel, and the
+ * temporary AdkGeminiAdapter (lib/models/adkGeminiAdapter.ts) runs its calls
+ * through generateWithRetries. registry.ts also builds that adapter in
+ * resolveAdapter, so the class living in registry.ts would be an ESM import
+ * cycle. registry.ts re-exports it, so `TracedGemini` imports from there keep
+ * working.
+ */
+import { Gemini } from '@google/adk';
+import { endpointFromEnv, platformModel } from './endpoints.js';
+import { llmRequestToModelRequest } from './genaiMapping.js';
+import { errorStatus, retryUntilFirstYield } from './retry.js';
+import { setLlmSpanAttribute, traceLlmGeneration } from '../observability/tracer.js';
+import { currentTurnSignal } from '../runtime/turnControl.js';
+export class TracedGemini extends Gemini {
+    // CRITICAL: reuse Gemini's exact regex instances. The LLMRegistry dict is
+    // keyed by the regex OBJECT — registering the same instances REPLACES the
+    // built-in Gemini entries instead of adding shadowed duplicates.
+    static supportedModels = Gemini.supportedModels;
+    /**
+     * The Gemini platform (ADR 0023) applies to every construction, the
+     * LLMRegistry's included: on Vertex AI the client authenticates with
+     * Google Application Default Credentials for the configured project and
+     * location, and an AI Studio key (the environment's or a caller's) is not
+     * sent. `endpoint` overrides the environment's (the credentials plug point).
+     */
+    constructor(params = {}) {
+        const { endpoint: given, ...rest } = params;
+        const e = given ?? endpointFromEnv('gemini');
+        const model = rest.model ? platformModel(e, rest.model) : rest.model;
+        super(e.platform === 'vertex'
+            ? { ...rest, model, apiKey: e.apiKey, vertexai: true, project: e.project, location: e.location }
+            : { ...rest, model, ...(e.apiKey && !rest.apiKey ? { apiKey: e.apiKey } : {}) });
+        this.#vertex = e.platform === 'vertex';
+    }
+    /** True when the client runs on Vertex AI (ADR 0023). */
+    #vertex;
+    async *generateContentAsync(llmRequest, stream, abortSignal) {
+        yield* traceLlmGeneration({
+            provider: 'gemini',
+            model: this.model,
+            request: () => llmRequestToModelRequest(llmRequest, { model: llmRequest.model || this.model, stream }),
+        }, this.generateWithRetries(llmRequest, stream, abortSignal ?? currentTurnSignal()));
+    }
+    /**
+     * One call through ADK's Gemini with the shared retries, tagging whatever
+     * llm.request span is active (llm.web_search.native for Gemini grounding,
+     * llm.retries, llm.http_status). generateContentAsync opens that span
+     * around it; AdkGeminiAdapter (lib/models/adkGeminiAdapter.ts) runs it
+     * inside the span its own caller opens (ADR 0053). A failed call throws,
+     * as ADK's Gemini does. The abort signal is forwarded so a canceled turn stops the
+     * request in flight (ADK's Gemini puts it on the genai request config).
+     */
+    async *generateWithRetries(llmRequest, stream, abortSignal) {
+        // The compiler asks every agent's config for includeServerSideToolInvocations
+        // (lib/compile.ts), which the Gemini API needs beside function
+        // declarations. @google/genai refuses it on Vertex AI before any request
+        // is sent ("only supported in Gemini Developer API mode"), so on Vertex
+        // it is left off, and the call goes out as it did before the flag.
+        const toolConfig = llmRequest.config?.toolConfig;
+        if (this.#vertex && toolConfig && 'includeServerSideToolInvocations' in toolConfig) {
+            const { includeServerSideToolInvocations: _vertexRefuses, ...kept } = toolConfig;
+            llmRequest.config = { ...llmRequest.config, toolConfig: kept };
+        }
+        const hasGrounding = (llmRequest.config?.tools ?? []).some((t) => t && (t.googleSearch || t.googleSearchRetrieval));
+        if (hasGrounding)
+            setLlmSpanAttribute('llm.web_search.native', true);
+        // Retries live here, not in genai's own httpOptions.retryOptions: that
+        // hook (p-retry 4, client-level only) ignores the abort signal — it
+        // sleeps and re-sends after a canceled turn — honours no Retry-After,
+        // does not retry Node's "fetch failed" resets, and replaces a 4xx's
+        // error body (e.g. "API key not valid") with a bare statusText. Wrapping
+        // the call keeps genai's ApiError intact and applies the same policy as
+        // every other adapter. A retry is only made while nothing has been
+        // yielded, so a stream that fails mid-reply is surfaced, not replayed.
+        // ADK's request preprocessing is idempotent, so re-sending the same
+        // llmRequest is safe. The registry class, resolveModel()'s per-request
+        // instances and AdkGeminiAdapter's are all TracedGemini, so all get this.
+        try {
+            yield* retryUntilFirstYield(() => super.generateContentAsync(llmRequest, stream, abortSignal), {
+                signal: abortSignal,
+                onRetry: ({ retries }) => setLlmSpanAttribute('llm.retries', retries),
+            });
+        }
+        catch (err) {
+            // genai's ApiError carries the status; put it where the ledger reads.
+            const status = errorStatus(err);
+            if (status !== undefined)
+                setLlmSpanAttribute('llm.http_status', status);
+            throw err;
+        }
+    }
+}

package/dist/lib/models/urls.d.ts

@@ -0,0 +1,11 @@
+/**
+ * lib/models/urls.ts — small URL helpers shared by the adapters, the
+ * gateway, the endpoints module and the embeddings provider.
+ *
+ * WHY: `url.replace(/\/+$/, '')` backtracks quadratically on a long run of
+ * slashes followed by another character (CodeQL js/polynomial-redos), and
+ * a base URL can come from an environment variable or a caller's option.
+ * This scans from the end once.
+ */
+/** `url` without its trailing slashes, in one pass from the end. */
+export declare function trimTrailingSlashes(url: string): string;

package/dist/lib/models/urls.js

@@ -0,0 +1,16 @@
+/**
+ * lib/models/urls.ts — small URL helpers shared by the adapters, the
+ * gateway, the endpoints module and the embeddings provider.
+ *
+ * WHY: `url.replace(/\/+$/, '')` backtracks quadratically on a long run of
+ * slashes followed by another character (CodeQL js/polynomial-redos), and
+ * a base URL can come from an environment variable or a caller's option.
+ * This scans from the end once.
+ */
+/** `url` without its trailing slashes, in one pass from the end. */
+export function trimTrailingSlashes(url) {
+    let end = url.length;
+    while (end > 0 && url.charCodeAt(end - 1) === 47 /* '/' */)
+        end--;
+    return url.slice(0, end);
+}

package/dist/lib/net/redirects.d.ts

@@ -1,3 +1,24 @@
+/**
+ * lib/net/redirects.ts — follow HTTP redirects one hop at a time, each hop
+ * held to a policy, for code that makes its own requests.
+ *
+ * WHY: fetch follows redirects by default, so a guard that vets only the URL
+ * a request starts at is bypassed by any server that answers 302: an allowed
+ * public API with an open redirect can send a call to 169.254.169.254, and
+ * fetch forwards every header but Authorization and Cookie (an API key in a
+ * custom header crosses origins). web_extract follows redirects manually for
+ * this reason, and so do the OpenAPI tools (lib/tools/openapi/call.ts) and
+ * the MCP client (lib/tools/mcpToolFactory.ts), through this module.
+ *
+ * HOW: `fetchWithRedirectPolicy(input, init, policy, fetch)` sends every
+ * request with `redirect: 'manual'`; each hop's URL goes to
+ * `policy.hopProblem` before it is fetched, a hop to another origin keeps
+ * only content-negotiation headers, and a chain longer than MAX_REDIRECTS is
+ * an error. 303, and 301/302 after a POST, continue as a GET without a body,
+ * as browsers do. The policy is a parameter of the call: nothing is
+ * installed on globalThis.fetch (ADR 0067 retired the context-scoped
+ * wrapper ADR 0036 put there while ADK made the OpenAPI requests).
+ */
 export declare const MAX_REDIRECTS = 5;
 export interface RedirectPolicy {
     /** Why the request may not follow a redirect to `url`, or null to follow it. */
@@ -9,6 +30,4 @@ type Fetch = typeof globalThis.fetch;
  * Throws when a hop is refused or the chain is too long.
  */
 export declare function fetchWithRedirectPolicy(input: string | URL | Request, init: RequestInit | undefined, policy: RedirectPolicy, fetchImpl: Fetch): Promise<Response>;
-/** Run `fn` with every globalThis.fetch it makes following redirects under `policy`. */
-export declare function withRedirectGuard<T>(policy: RedirectPolicy, fn: () => Promise<T>): Promise<T>;
 export {};