melchizedek-agents 0.20.0 → 1.0.0

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

@@ -4,12 +4,12 @@
  * implements and the native runtime calls (ADR 0045, ADR 0048).
  *
  * WHY this file exists:
- *   The ADK runtime speaks @google/genai `Content`, which is Gemini's wire
- *   format. It has no slot for another provider's reasoning state, spells
- *   schemas in Gemini's uppercase dialect, carries server-side tools as
- *   sentinel tool objects, and surfaces failures as a throw on one path and
- *   a yielded `errorCode` on another. The native runtime owns its loop, so it
- *   owns this format instead. Each adapter translates it to its provider's
+ *   ADK spoke @google/genai `Content`, which is Gemini's wire format. It
+ *   has no slot for another provider's reasoning state, spells schemas in
+ *   Gemini's uppercase dialect, carried server-side tools as sentinel tool
+ *   objects, and surfaced failures as a throw on one path and a yielded
+ *   `errorCode` on another. The native runtime owns its loop, so it owns
+ *   this format instead. Each adapter translates it to its provider's
  *   wire; wiki/models/model-contract.md is the field-by-field spec, with the
  *   mapping for every provider.
  *
@@ -290,9 +290,9 @@ type SetupErrorCode = 'MISSING_API_KEY' | 'ENDPOINT_MISCONFIGURED' | 'SDK_NOT_IN
 /** The chat-completions failures, under the provider's id (the gateway names the upstream provider). */
 type ChatErrorCode = `${'MOONSHOT' | 'OLLAMA' | 'GEMINI' | 'ANTHROPIC' | 'OPENAI' | 'XAI'}_${'MAX_TOKENS' | 'EMPTY_RESPONSE' | 'UNREACHABLE'}` | 'MOONSHOT_MISSING_KEY' | 'MOONSHOT_HTTP_ERROR' | 'OLLAMA_HTTP_ERROR' | 'GATEWAY_NOT_CONFIGURED' | 'GATEWAY_KEY_MISSING' | 'GATEWAY_HTTP_ERROR';
 /**
- * Gemini's codes: ADK's adapter reports a candidate's finish reason, or the
- * prompt's block reason, as the code itself. GEMINI_ERROR is a failed call,
- * which ADK throws and the contract reports.
+ * Gemini's codes: a candidate's finish reason, or the prompt's block reason,
+ * is the code itself, as ADK's adapter reported it. GEMINI_ERROR is a failed
+ * call, which ADK threw and the contract reports.
  */
 type GeminiErrorCode = 'GEMINI_ERROR' | 'MAX_TOKENS' | 'SAFETY' | 'RECITATION' | 'LANGUAGE' | 'OTHER' | 'BLOCKLIST' | 'PROHIBITED_CONTENT' | 'SPII' | 'MALFORMED_FUNCTION_CALL' | 'IMAGE_SAFETY' | 'UNEXPECTED_TOOL_CALL' | 'TOO_MANY_TOOL_CALLS' | 'IMAGE_PROHIBITED_CONTENT' | 'NO_IMAGE' | 'IMAGE_RECITATION' | 'IMAGE_OTHER' | 'MODEL_ARMOR' | 'JAILBREAK' | 'UNKNOWN_ERROR';
 /**
@@ -302,8 +302,8 @@ type GeminiErrorCode = 'GEMINI_ERROR' | 'MAX_TOKENS' | 'SAFETY' | 'RECITATION' |
  */
 type TurnControlErrorCode = 'STEP_LIMIT' | 'DEADLINE_EXCEEDED' | 'CANCELED';
 /**
- * The codes the engine's adapters report, kept verbatim from what they emit
- * under ADK so a caller matching on a code keeps working. An adapter the
+ * The codes the engine's adapters report, kept verbatim from what they
+ * emitted under ADK so a caller matching on a code keeps working. An adapter the
  * engine does not ship may report its own; the engine's adapters use only
  * these, and adding one is a change to wiki/models/model-contract.md.
  */

package/dist/lib/models/contract.js

@@ -4,12 +4,12 @@
  * implements and the native runtime calls (ADR 0045, ADR 0048).
  *
  * WHY this file exists:
- *   The ADK runtime speaks @google/genai `Content`, which is Gemini's wire
- *   format. It has no slot for another provider's reasoning state, spells
- *   schemas in Gemini's uppercase dialect, carries server-side tools as
- *   sentinel tool objects, and surfaces failures as a throw on one path and
- *   a yielded `errorCode` on another. The native runtime owns its loop, so it
- *   owns this format instead. Each adapter translates it to its provider's
+ *   ADK spoke @google/genai `Content`, which is Gemini's wire format. It
+ *   has no slot for another provider's reasoning state, spells schemas in
+ *   Gemini's uppercase dialect, carried server-side tools as sentinel tool
+ *   objects, and surfaced failures as a throw on one path and a yielded
+ *   `errorCode` on another. The native runtime owns its loop, so it owns
+ *   this format instead. Each adapter translates it to its provider's
  *   wire; wiki/models/model-contract.md is the field-by-field spec, with the
  *   mapping for every provider.
  *

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

@@ -1,16 +1,17 @@
 /**
- * lib/models/errorResponse.ts — an ADK adapter's error response, saying
- * whether another attempt or another model may succeed.
+ * lib/models/errorResponse.ts — what a failed provider call says about
+ * trying again, and the genai-shaped error response that carries it.
  *
- * WHY: every adapter but Gemini reports a failed provider call as a yielded
- * LlmResponse carrying `errorCode`, never a throw. FallbackLlm
- * (lib/models/fallback.ts, ADR 0044) must tell a provider-side failure from
- * the request's own error without parsing a message, so an adapter's catch
- * site builds that response here, with the retry policy's verdict in its
- * customMetadata (Claude, GPT and Grok, and the chat-completions base for
- * Kimi, Ollama and the gateway). A
- * response without the verdict is read as not retryable: passed on, never
- * redirected.
+ * WHY: an adapter reports a failed provider call as a final response with
+ * `error`, never a throw, and the fallback (FallbackAdapter,
+ * lib/models/fallbackAdapter.ts, ADR 0044) must tell a provider-side
+ * failure from the request's own error without parsing a message. The
+ * adapters' catch sites (Claude, GPT and Grok, and the chat-completions base
+ * for Kimi, Ollama and the gateway) take the verdict and the scrubbed text
+ * from here (errorDecision, statusDecision, errorText). A genai-shaped
+ * LlmResponse (lib/models/genaiMapping.ts) carries the same verdict in its
+ * customMetadata (withRetryVerdict). A response without the verdict is read
+ * as not retryable: passed on, never redirected.
  *
  *   'error.retryable'  true when lib/models/retry.ts classifies the failure
  *                      retryable (408/409/425/429/5xx, a connection reset);
@@ -22,7 +23,7 @@
  * leaves the adapter, so an error never carries a key into a session, the
  * ledger or a log.
  */
-import type { LlmResponse } from '@google/adk';
+import type { LlmResponse } from './genaiMapping.ts';
 import type { RetryDecision } from './retry.ts';
 /** customMetadata key: whether another attempt or model may succeed. */
 export declare const ERROR_RETRYABLE_KEY = "error.retryable";
@@ -40,11 +41,3 @@ export declare function statusDecision(status: number): RetryDecision;
  * the adapter's own; customMetadata it already carries is kept.
  */
 export declare function withRetryVerdict(response: LlmResponse, decision: RetryDecision): LlmResponse;
-/**
- * The error response for a caught provider error: `errorCode`, the message
- * (the error's own text unless the adapter words it), and the verdict from
- * classifyError.
- */
-export declare function providerErrorResponse(err: unknown, errorCode: string, errorMessage?: string): LlmResponse;
-/** True when a response is an error its adapter marked retryable: a provider-side failure. */
-export declare function isRetryableErrorResponse(response: LlmResponse): boolean;

package/dist/lib/models/errorResponse.js

@@ -34,15 +34,3 @@ export function withRetryVerdict(response, decision) {
         },
     };
 }
-/**
- * The error response for a caught provider error: `errorCode`, the message
- * (the error's own text unless the adapter words it), and the verdict from
- * classifyError.
- */
-export function providerErrorResponse(err, errorCode, errorMessage = errorText(err)) {
-    return withRetryVerdict({ errorCode, errorMessage }, errorDecision(err));
-}
-/** True when a response is an error its adapter marked retryable: a provider-side failure. */
-export function isRetryableErrorResponse(response) {
-    return !!response.errorCode && response.customMetadata?.[ERROR_RETRYABLE_KEY] === true;
-}

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

@@ -2,11 +2,10 @@
  * lib/models/fallbackAdapter.ts — `fallback_model:` and the per-provider
  * circuit breaker (ADR 0044) on the engine's own model contract (ADR 0048).
  *
- * WHY: FallbackLlm (lib/models/fallback.ts) wraps two ADK BaseLlm adapters
- * and reads a failure from a throw. On the contract a failure is a final
- * response with `error` set, never a throw, and `error.retryable` already
- * says whether another model may succeed. This wrapper is the same rule set
- * read from that: one ModelAdapter around a primary and a fallback adapter.
+ * WHY: on the contract a failure is a final response with `error` set,
+ * never a throw, and `error.retryable` already says whether another model
+ * may succeed. This wrapper is ADR 0044's rule set read from that: one
+ * ModelAdapter around a primary and a fallback adapter.
  *
  * THE RULES (ADR 0044, unchanged):
  *   - Only a provider-side failure counts and redirects: `error.retryable`
@@ -19,9 +18,9 @@
  *     was yielded and the failed final holds no parts. A call that failed
  *     midway is passed on, never replayed on another model.
  *   - The breaker (lib/models/circuitBreaker.ts) is keyed on the primary's
- *     `provider` and shared with FallbackLlm, so a provider tripped on one
- *     path is skipped on the other. While it is open the primary is not
- *     called. A success closes it; the fallback's own outcome is not counted.
+ *     `provider` and shared by every wrapped agent in the process, so a
+ *     provider tripped for one agent is skipped for the others. While it is
+ *     open the primary is not called. A success closes it; the fallback's own outcome is not counted.
  *
  * THE FALLBACK'S REQUEST: the caller's request with `model` rewritten to the
  * fallback's id. `reasoning` goes unchanged, and the fallback adapter maps it

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

@@ -8,7 +8,7 @@
  *   (lib/models/gateway.ts owns that decision). It extends the
  *   chat-completions base (lib/models/chatCompletionsAdapter.ts) the way
  *   Ollama does, because chat completions is the one dialect every gateway
- *   serves. Under ADK it runs behind GatewayLlm (lib/models/gatewayLlm.ts).
+ *   serves.
  *
  * WHAT STAYS TRUE THROUGH THE GATEWAY:
  *   - Attribution. `provider` is the YAML id's provider (anthropic, openai,

package/dist/lib/models/gatewayAdapter.js

@@ -8,7 +8,7 @@
  *   (lib/models/gateway.ts owns that decision). It extends the
  *   chat-completions base (lib/models/chatCompletionsAdapter.ts) the way
  *   Ollama does, because chat completions is the one dialect every gateway
- *   serves. Under ADK it runs behind GatewayLlm (lib/models/gatewayLlm.ts).
+ *   serves.
  *
  * WHAT STAYS TRUE THROUGH THE GATEWAY:
  *   - Attribution. `provider` is the YAML id's provider (anthropic, openai,

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

@@ -3,12 +3,11 @@
  * contract (lib/models/contract.ts, ADR 0048), on @google/genai directly.
  *
  * WHY this file exists:
- *   Gemini runs today through ADK's own Gemini class, wrapped as
- *   TracedGemini (lib/models/tracedGemini.ts). The native runtime (ADR 0045)
- *   needs Gemini as a contract ModelAdapter that shapes its own requests,
- *   aggregates its own stream and reports its own failures, with no ADK in
- *   the path. This is that adapter. resolveAdapter (lib/models/registry.ts)
- *   returns it only when asked (GEMINI_ADAPTER=engine) until gate G3.
+ *   The native loop (ADR 0045) needs Gemini as a contract ModelAdapter that
+ *   shapes its own requests, aggregates its own stream and reports its own
+ *   failures. This is that adapter, and the only Gemini adapter:
+ *   resolveAdapter (lib/models/adapterResolver.ts) returns it for every
+ *   Gemini id (ADR 0100, ADR 0107).
  *
  * THE MAPPING is the Gemini table of wiki/models/model-contract.md;
  * wiki/models/gemini-adapter.md records the choices made inside it:

package/dist/lib/models/geminiAdapter.js

@@ -3,12 +3,11 @@
  * contract (lib/models/contract.ts, ADR 0048), on @google/genai directly.
  *
  * WHY this file exists:
- *   Gemini runs today through ADK's own Gemini class, wrapped as
- *   TracedGemini (lib/models/tracedGemini.ts). The native runtime (ADR 0045)
- *   needs Gemini as a contract ModelAdapter that shapes its own requests,
- *   aggregates its own stream and reports its own failures, with no ADK in
- *   the path. This is that adapter. resolveAdapter (lib/models/registry.ts)
- *   returns it only when asked (GEMINI_ADAPTER=engine) until gate G3.
+ *   The native loop (ADR 0045) needs Gemini as a contract ModelAdapter that
+ *   shapes its own requests, aggregates its own stream and reports its own
+ *   failures. This is that adapter, and the only Gemini adapter:
+ *   resolveAdapter (lib/models/adapterResolver.ts) returns it for every
+ *   Gemini id (ADR 0100, ADR 0107).
  *
  * THE MAPPING is the Gemini table of wiki/models/model-contract.md;
  * wiki/models/gemini-adapter.md records the choices made inside it:
@@ -102,8 +101,8 @@ export class GeminiAdapter {
         this.#placeholderSignatures = options.placeholderSignatures ?? PLACEHOLDER_SIGNATURES_BY_DEFAULT;
     }
     async *generate(request) {
-        // The request's signal alone: the caller (the ADK shim, the native loop)
-        // passes the turn's (ADR 0053).
+        // The request's signal alone: the caller (the native loop) passes the
+        // turn's (ADR 0053).
         const signal = request.signal;
         const model = request.model || this.model;
         const reply = new ReplyBuilder(model, request.messages.length);
@@ -277,8 +276,8 @@ function buildRequest(request, options) {
     const native = tools.length > (declared ? 1 : 0);
     let toolConfig = toolConfigFor(request);
     // Native tools beside function declarations: the response carries the
-    // server-side invocations, as the ADK path asks on every Gemini agent
-    // (lib/compile.ts). The SDK refuses the flag for Vertex AI.
+    // server-side invocations, as ADK asked on every Gemini agent. The SDK
+    // refuses the flag for Vertex AI.
     if (declared && native && options.geminiApi)
         toolConfig = { ...toolConfig, includeServerSideToolInvocations: true };
     if (toolConfig)

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

@@ -3,15 +3,15 @@
  * written under (ADR 0046), and the prefix of a call id the genai mapping
  * mints, in one place.
  *
- * WHY: three modules write or replay a Gemini `thoughtSignature` as
- * `providerState`: the genai mapping (lib/models/genaiMapping.ts), the
- * engine's own Gemini adapter (lib/models/geminiAdapter.ts) and the wrapper
- * over ADK's Gemini (lib/models/adkGeminiAdapter.ts). A reader replays only
- * the provider and kind it wrote (`providerStateOf`), so the three must spell
- * them the same. Each re-exports these names where they were exported before.
+ * WHY: two modules write or replay a Gemini `thoughtSignature` as
+ * `providerState`: the genai mapping (lib/models/genaiMapping.ts) and the
+ * engine's Gemini adapter (lib/models/geminiAdapter.ts). A reader replays
+ * only the provider and kind it wrote (`providerStateOf`), so the two must
+ * spell them the same. Each re-exports these names where they were exported
+ * before.
  *
- * A leaf with no imports, so the Gemini adapter takes the ids without the
- * mapping, whose import graph names ADK's types.
+ * A leaf with no imports, so a module takes the ids without the mapping and
+ * its @google/genai import graph.
  */
 /** The provider id the Gemini adapters report, and write their state under (lib/models/providerMap.ts). */
 export declare const GEMINI_PROVIDER = "gemini";

package/dist/lib/models/geminiState.js

@@ -3,15 +3,15 @@
  * written under (ADR 0046), and the prefix of a call id the genai mapping
  * mints, in one place.
  *
- * WHY: three modules write or replay a Gemini `thoughtSignature` as
- * `providerState`: the genai mapping (lib/models/genaiMapping.ts), the
- * engine's own Gemini adapter (lib/models/geminiAdapter.ts) and the wrapper
- * over ADK's Gemini (lib/models/adkGeminiAdapter.ts). A reader replays only
- * the provider and kind it wrote (`providerStateOf`), so the three must spell
- * them the same. Each re-exports these names where they were exported before.
+ * WHY: two modules write or replay a Gemini `thoughtSignature` as
+ * `providerState`: the genai mapping (lib/models/genaiMapping.ts) and the
+ * engine's Gemini adapter (lib/models/geminiAdapter.ts). A reader replays
+ * only the provider and kind it wrote (`providerStateOf`), so the two must
+ * spell them the same. Each re-exports these names where they were exported
+ * before.
  *
- * A leaf with no imports, so the Gemini adapter takes the ids without the
- * mapping, whose import graph names ADK's types.
+ * A leaf with no imports, so a module takes the ids without the mapping and
+ * its @google/genai import graph.
  */
 /** The provider id the Gemini adapters report, and write their state under (lib/models/providerMap.ts). */
 export const GEMINI_PROVIDER = 'gemini';

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

@@ -1,16 +1,15 @@
 /**
- * lib/models/genaiMapping.ts — @google/genai `Content`, and ADK's LlmRequest
- * and LlmResponse, to and from the engine's model contract
+ * lib/models/genaiMapping.ts — @google/genai `Content`, and the genai-shaped
+ * LlmRequest and LlmResponse, to and from the engine's model contract
  * (lib/models/contract.ts, ADR 0048).
  *
  * WHY this file exists:
- *   The ADK runtime holds and stores @google/genai `Content`: the history of
- *   an LlmRequest, and the `content` of every stored event. The native
- *   runtime and every adapter on the contract speak `Message` and `Part`.
- *   This module converts between the two, so the native runtime can read a
- *   session ADK stored, and an adapter can move onto the contract while ADK
- *   still runs: its ADK class maps the LlmRequest in and each ModelResponse
- *   out. It is pure (no I/O, clock or randomness) and never mutates its
+ *   Every stored event's `content` is @google/genai `Content`, the shape ADK
+ *   wrote and the engine keeps (ADR 0045's fixed shapes). The native loop
+ *   and every adapter on the contract speak `Message` and `Part`. This
+ *   module converts between the two, so the loop reads a session ADK stored
+ *   before 1.0.0 as it reads its own, and stores each answer in the same
+ *   shape (modelResponseToLlmResponse). It is pure (no I/O, clock or randomness) and never mutates its
  *   input; leaf values (args, results, payloads) are shared, not copied.
  *   The contract stays a leaf: only this module names @google/*.
  *   wiki/models/model-contract.md ("From genai Content") is the spec.
@@ -63,7 +62,8 @@
  *   genai bytes cannot tell the two apart.
  *
  *   Ids. A ToolCallPart always has an id. A genai call without one (Gemini
- *   returns none, and ADK strips its own `adk-` ids from every request) gets
+ *   returns none, and the engine strips its own `adk-` ids from every
+ *   request, as ADK did) gets
  *   `genai-noid-<content>-<part>`, from its position, and a result without
  *   one takes the id of the latest open minted call of the same name, else
  *   one of its own (it then answers no call in the history). Back, a minted
@@ -91,27 +91,24 @@
  * true`; usage in Gemini's meanings (usageToMetadata); error as `errorCode`
  * and `errorMessage`, key-shaped text scrubbed, with `retryable` and
  * `status` as customMetadata['error.retryable'] and ['error.status']
- * (withRetryVerdict, lib/models/errorResponse.ts), the only place
- * FallbackLlm reads whether a fallback may answer; finishReason as
+ * (withRetryVerdict, lib/models/errorResponse.ts); finishReason as
  * Gemini's, except that an error whose code is one of Gemini's finish
- * reasons (the Gemini adapters keep it verbatim: MALFORMED_FUNCTION_CALL,
- * RECITATION, ...) gets that reason itself, as ADK's Gemini reports both, so
- * self-correction retries a malformed call and the stored event reads the
- * same on either runtime (ADR 0088); grounding as the `webSearchQueries` and
+ * reasons (the Gemini adapter keeps it verbatim: MALFORMED_FUNCTION_CALL,
+ * RECITATION, ...) gets that reason itself, as ADK's Gemini reported both,
+ * so self-correction retries a malformed call and the stored event reads as
+ * one ADK stored (ADR 0088); grounding as the `webSearchQueries` and
  * `groundingChunks[].web` that lib/grounding.ts reads. Not carried, since
  * an LlmResponse has no field for them: `cacheWriteTokens`, a citation's
  * span and cited text, and which native tool ran a query.
  *
- * THE REVERSE: a contract adapter over an ADK BaseLlm (lib/models/
- * adkGeminiAdapter.ts, the wrapper over ADK's Gemini) maps the ModelRequest
- * it is given to an LlmRequest, and each LlmResponse back.
+ * THE REVERSE: a ModelRequest as a genai-shaped LlmRequest, and each
+ * LlmResponse back, for a caller that holds a genai-speaking model.
  *
- *   modelRequestToLlmRequest builds the LlmRequest ADK's path builds for a
- *   Gemini model: the system prompt as `systemInstruction`; the messages as
+ *   modelRequestToLlmRequest builds the genai-shaped request for a Gemini
+ *   model: the system prompt as `systemInstruction`; the messages as
  *   above; client tools as `functionDeclarations` with the lowercase schema
  *   in `parametersJsonSchema`, and in `toolsDict` as declaration-only
- *   entries, where llmRequestToModelRequest and the ADK-path adapters read
- *   them; native tools as Gemini's tool objects, in the request's order;
+ *   entries, where llmRequestToModelRequest reads them; native tools as Gemini's tool objects, in the request's order;
  *   toolChoice and strict as the function-calling mode, sent only beside
  *   declarations; the output schema as `responseJsonSchema`, and
  *   `outputFormat: 'json'` without one as `responseMimeType:
@@ -120,7 +117,7 @@
  *   it; sampling; the signal as `config.abortSignal`. What does not come
  *   back the same through llmRequestToModelRequest: `google_search` reads as
  *   `web_search`; `x_search` and `collections_search` are left out (Gemini
- *   has no tool for them, and ADK adds their sentinels only for xAI); `auto`
+ *   has no tool for them, and they go only to xAI); `auto`
  *   reads as absent, and a choice without tools is not sent; one strict tool
  *   makes every tool strict, and strict is lost beside a forced choice; a
  *   level a model renders as a budget or another word reads back as that
@@ -144,15 +141,64 @@
  *   display only (the caller yields it as a partial).
  *
  * USAGE MEANINGS. usageToMetadata and usageFromMetadata use Gemini's: its
- * `candidatesTokenCount` excludes the thinking in `thoughtsTokenCount`. The
- * ADK-path GPT and chat-completions adapters write `candidatesTokenCount`
- * with reasoning included, so usageFromMetadata on an event they stored
- * counts that reasoning twice in `outputTokens`.
+ * `candidatesTokenCount` excludes the thinking in `thoughtsTokenCount`.
+ * Every adapter's final is stored and charged through usageToMetadata, so
+ * this is the ledger's one meaning for every provider (ADR 0107).
+ * Events the GPT and chat-completions adapters stored under ADK (before
+ * 1.0.0) carry `candidatesTokenCount` with reasoning included, so
+ * usageFromMetadata on such an event counts that reasoning twice in
+ * `outputTokens`.
  */
-import type { Content, ContentUnion, GenerateContentConfig, GenerateContentResponseUsageMetadata, Part as GenaiPart } from '@google/genai';
-import type { LlmRequest, LlmResponse } from '@google/adk';
+import { FinishReason } from '@google/genai';
+import type { Content, ContentUnion, GenerateContentConfig, GenerateContentResponseUsageMetadata, GroundingMetadata, Part as GenaiPart, CitationMetadata } from '@google/genai';
 import type { Message, ModelRequest, ModelResponse, NativeTool, Part, ReasoningSetting, Sampling, ToolChoice, Usage } from './contract.ts';
 import { GEMINI_PROVIDER, GENAI_PART_KIND, MINTED_CALL_ID_PREFIX, THOUGHT_SIGNATURE_KIND } from './geminiState.ts';
+/**
+ * A tool as a request's `toolsDict` holds it: a name and, for a function
+ * tool, `_getDeclaration()` giving its declaration with a lowercase schema as
+ * `parameters` (contractToolDeclaration reads it). A server-side tool carries
+ * its NativeTool marker instead (lib/tools/tool.ts NATIVE_TOOL).
+ */
+export interface DeclaredTool {
+    name: string;
+    description?: string;
+    isLongRunning?: boolean;
+    _getDeclaration?(): unknown;
+    [key: string | symbol]: unknown;
+}
+/**
+ * One model request in genai's shape: the JSON ADK's LlmRequest carried,
+ * owned by the engine since 1.0.0. The summarizer, the memory extractor and
+ * the tracer build or read it; llmRequestToModelRequest maps it onto the
+ * contract.
+ */
+export interface LlmRequest {
+    model?: string;
+    contents: Content[];
+    config?: GenerateContentConfig;
+    liveConnectConfig?: Record<string, unknown>;
+    toolsDict: Record<string, DeclaredTool>;
+    allowedTools?: string[];
+}
+/**
+ * One model response in genai's shape: the JSON ADK's LlmResponse carried,
+ * and what a stored model event is made from (lib/runtime/native/step.ts).
+ * Owned by the engine since 1.0.0.
+ */
+export interface LlmResponse {
+    content?: Content;
+    groundingMetadata?: GroundingMetadata;
+    citationMetadata?: CitationMetadata;
+    partial?: boolean;
+    turnComplete?: boolean;
+    errorCode?: string;
+    errorMessage?: string;
+    interrupted?: boolean;
+    customMetadata?: Record<string, unknown>;
+    usageMetadata?: GenerateContentResponseUsageMetadata;
+    finishReason?: FinishReason;
+    modelVersion?: string;
+}
 /**
  * The provider id the mapping writes its own state under (only a Gemini
  * adapter replays it), and the providerState kind for a Gemini
@@ -209,7 +255,7 @@ export declare function messagesToContents(history: {
     system?: string;
     messages: readonly Message[];
 }): GenaiHistory;
-/** What an LlmRequest does not carry: ADK passes these to generateContentAsync beside it. */
+/** What an LlmRequest does not carry: the caller passes these beside it, as ADK did to generateContentAsync. */
 export interface ModelRequestOptions {
     /** The model id; default the request's own `model`. */
     model?: string;
@@ -239,7 +285,7 @@ export declare function toolChoiceOf(config: GenerateContentConfig | undefined):
 };
 /** The sampling fields the contract carries, or undefined when none is set. The native request builder reads an agent's config through it too. */
 export declare function samplingOf(config: GenerateContentConfig | undefined): Sampling | undefined;
-/** An ADK LlmRequest as a ModelRequest (see the header for what is not mapped). */
+/** A genai-shaped LlmRequest as a ModelRequest (see the header for what is not mapped). */
 export declare function llmRequestToModelRequest(llmRequest: LlmRequest, options?: ModelRequestOptions): ModelRequest;
 /**
  * Usage in Gemini's meanings: `candidatesTokenCount` excludes the thinking
@@ -254,17 +300,17 @@ export declare const TOO_DEEP_ARGUMENTS = "[arguments nested deeper than 64 leve
 /**
  * `response` with each part held to the contract (contractOutputPart): the
  * same object when every part already is, else a copy with the parts
- * checked. Used by modelResponseToLlmResponse (the ADK shim's mapping) and
- * by the native step, so both runtimes read and store the same answer. A
+ * checked. Used by modelResponseToLlmResponse and by the native step, so the
+ * step reads the same answer it stores. A
  * response that is not an object is returned as it is: the caller fails on
  * it as on any adapter that broke the contract.
  */
 export declare function contractModelResponse<R extends ModelResponse>(response: R): R;
-/** A ModelResponse as the LlmResponse ADK expects from a model (see the header). */
+/** A ModelResponse as a genai-shaped LlmResponse, the shape a stored model event is made from (see the header). */
 export declare function modelResponseToLlmResponse(unchecked: ModelResponse): LlmResponse;
 /** The native tools in `tools` that Gemini has no tool for, each once: modelRequestToLlmRequest leaves them out. */
 export declare function nativeToolsWithoutGeminiTool(tools?: readonly NativeTool[]): NativeTool[];
-/** A ModelRequest as the LlmRequest ADK's path builds for a Gemini model (see the header for what does not come back the same). */
+/** A ModelRequest as the genai-shaped request for a Gemini model (see the header for what does not come back the same). */
 export declare function modelRequestToLlmRequest(request: ModelRequest): LlmRequest;
 /** What an LlmResponse does not carry, for the response it maps to. */
 export interface ModelResponseOptions {