melchizedek-agents 0.18.0 → 0.20.0

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

@@ -1,239 +1,96 @@
 /**
- * lib/models/openAiCompatibleLlm.ts — shared base class for every provider
- * that speaks the OpenAI chat-completions wire format.
+ * lib/models/openAiCompatibleLlm.ts — the ADK shim base for every
+ * chat-completions adapter (Ollama, Kimi, the gateway).
  *
  * WHY this file exists:
- *   Separates the OpenAI chat-completions wire translation (ADK Content →
- *   chat messages, tool-definition building, tool_call parsing, usage
- *   accounting, reasoning surfacing) from provider specifics, so any
- *   /chat/completions-speaking provider is a small subclass supplying only
- *   the endpoint, auth headers, wire model name, and extra body fields.
- *   Current subclass: Ollama (local, keyless). xAI Grok used to live here
- *   too, but xAI's Agent Tools API is Responses-shaped, so GrokLlm now
- *   subclasses GptLlm instead (see lib/models/grokLlm.ts).
+ *   The chat-completions translation lives on the engine's own model
+ *   contract, in lib/models/chatCompletionsAdapter.ts and one adapter per
+ *   provider (ollamaAdapter.ts, kimiAdapter.ts, gatewayAdapter.ts). ADK
+ *   still runs every turn (ADR 0045), so each adapter runs behind an ADK
+ *   BaseLlm: OllamaLlm, KimiLlm and GatewayLlm, subclasses of this class,
+ *   which is an AdkShim (lib/models/adkShim.ts, ADR 0053). The shim charges
+ *   the turn, opens the llm.request span and maps the request and responses;
+ *   the adapter does the provider's work.
  *
- * WHAT THE BASE PROVIDES (uniformly, for every subclass):
- *   - Tool schemas normalized to lowercase JSON-Schema types
- *     (lib/models/schemaNormalize.ts — the ADK/Gemini dialect is uppercase).
- *   - usage → LlmResponse.usageMetadata mapping (prompt_tokens →
- *     promptTokenCount, completion_tokens → candidatesTokenCount,
- *     completion_tokens_details.reasoning_tokens → thoughtsTokenCount),
- *     so traceAgentRun / traceLlmGeneration count tokens for every provider.
- *   - Reasoning ("<think>…</think>" blocks, reasoning_content fields)
- *     surfaced as a { text, thought: true } part in a partial response —
- *     printers display it dimmed; it never enters session history.
- *   - A per-request `llm.request` OpenTelemetry span (lib/observability).
- *   - Retries of transient failures (lib/models/retry.ts) before any byte
- *     is yielded, and HTTP errors carrying `status` + `retryable`.
- *   - web_search handling: subclasses with native search return its body
- *     fields from webSearchBodyFields(); those without return null and the
- *     base omits the tool with a one-time warning + span attribute.
+ * WHAT THIS CLASS ADDS TO THE SHIM (ADR 0057): the ADK path stays what it
+ * was before the adapters moved onto the contract.
+ *   - The request: an agent's older generateContentConfig spelling that the
+ *     contract leaves out rides beside it (olderSpellingOf): an effort word
+ *     that is no contract level (Kimi K3's `max`). JSON mode without a
+ *     schema is the contract's `outputFormat` (ADR 0061).
+ *   - The response: the final keeps the shape these classes always yielded,
+ *     which the ledger and FallbackLlm read. usageMetadata counts the
+ *     reasoning inside candidatesTokenCount, as the provider's
+ *     completion_tokens does, so llm.tokens.output and the turn's charge are
+ *     unchanged (the shim's default is Gemini's meaning, which excludes it).
+ *     finishReason is set only for a reply cut short (MAX_TOKENS); a final
+ *     with no parts keeps its empty content; an HTTP failure keeps its
+ *     top-level `status` and `retryable` beside the verdict in
+ *     customMetadata.
+ *
+ * A /chat/completions provider of your own is a ChatCompletionsAdapter
+ * subclass (the endpoint, headers, wire name, reasoning field and error
+ * wording), run under ADK as `adkShim(adapter)` or as a subclass of this
+ * class.
  */
-import { BaseLlm } from '@google/adk';
+import type { GenerateContentConfig } from '@google/genai';
 import type { LlmRequest, LlmResponse } from '@google/adk';
-import type { BaseLlmConnection } from '@google/adk';
-type OpenAiContentPart = {
-    type: 'text';
-    text: string;
-} | {
-    type: 'image_url';
-    image_url: {
-        url: string;
-    };
-};
-type OpenAiMessage = {
-    role: 'system';
-    content: string;
-} | {
-    role: 'user';
-    content: string | OpenAiContentPart[];
-} | {
-    role: 'assistant';
-    content: string | null;
-    tool_calls?: Array<{
-        id: string;
-        type: 'function';
-        function: {
-            name: string;
-            arguments: string;
-        };
-    }>;
-} | {
-    role: 'tool';
-    tool_call_id: string;
-    content: string;
-};
+import { AdkShim } from './adkShim.ts';
+import type { AdkShimOptions } from './adkShim.ts';
+import type { ModelResponse, Usage } from './contract.ts';
+import type { ModelRequestOptions } from './genaiMapping.ts';
+import type { ChatCompletionsAdapter, ChatCompletionsRequest, ChatMessage, OlderSpelling } from './chatCompletionsAdapter.ts';
+export { REASONING_CONTENT_KIND, splitThinkBlocks, ThinkStreamSplitter } from './chatCompletionsAdapter.ts';
 /**
- * Splits "<think>…</think>" scratchpad from the reply.
- *
- * A block the model never closed is scratchpad too: it means the model ran
- * out of budget mid-thought, so everything after the opening tag is
- * reasoning — never reply text with a raw "<think>" in it.
+ * What a generateContentConfig asks of a chat-completions provider that the
+ * contract has no field for, or undefined when it asks nothing more:
+ * `reasoningEffort` when it is a word no ReasoningSetting carries (`max`,
+ * `xhigh`), sent as written. JSON mode without a schema is no longer here:
+ * the genai mapping reads it as `outputFormat: 'json'` (ADR 0061).
  */
-export declare function splitThinkBlocks(text: string): {
-    reasoning: string;
-    answer: string;
-};
+export declare function olderSpellingOf(config: GenerateContentConfig | undefined): OlderSpelling | undefined;
 /**
- * Incremental counterpart to splitThinkBlocks, for the SSE path.
- *
- * WHY a state machine rather than the regex: on a stream the closing
- * `</think>` has usually NOT arrived yet, so the regex matches nothing and
- * the whole scratchpad would be printed as the reply. A tag can also be
- * split mid-delta ("<thi" + "nk>"), so any tail that could still grow into
- * a tag is held back instead of being emitted as answer text.
- *
- * Providers that report reasoning in a discrete field (Ollama's
- * `delta.reasoning`, others' `reasoning_content`) never open a think block
- * and pass straight through this untouched.
+ * Usage as the chat-completions classes have always reported it on the ADK
+ * path: candidatesTokenCount is the provider's completion_tokens, reasoning
+ * included, and thoughtsTokenCount the reasoning part of it.
  */
-export declare class ThinkStreamSplitter {
-    private inThink;
-    private held;
-    /** Routes one content delta into reasoning/answer text. */
-    push(chunk: string): {
-        reasoning: string;
-        answer: string;
-    };
-    /** Releases the held tail; the stream ended, so it was never a tag. */
-    flush(): {
-        reasoning: string;
-        answer: string;
-    };
-}
-export declare abstract class OpenAiCompatibleLlm extends BaseLlm {
-    private webSearchWarned;
-    private retryWarned;
-    /** Provider id for telemetry, e.g. 'ollama', 'xai'. */
-    protected abstract providerId(): string;
-    /** Full chat-completions URL, e.g. "https://api.x.ai/v1/chat/completions". */
-    protected abstract endpointUrl(): string;
-    /** Auth/extra headers. Content-Type is added by the base. */
-    protected abstract headers(): Record<string, string>;
-    /** Model id as the wire expects it (e.g. strip the "ollama/" namespace). */
-    protected wireModelName(): string;
-    /**
-     * How the request reaches the provider: 'direct' (the provider's own
-     * endpoint) or 'gateway:<id>' (lib/models/gatewayLlm.ts). Recorded on the
-     * llm.request span as llm.transport so the ledger can tell a native call
-     * from a proxied one while llm.provider keeps the upstream attribution.
-     */
+export declare function chatUsageMetadata(usage: Usage): NonNullable<LlmResponse['usageMetadata']>;
+export declare abstract class OpenAiCompatibleLlm extends AdkShim {
+    readonly adapter: ChatCompletionsAdapter;
+    constructor(adapter: ChatCompletionsAdapter, options?: AdkShimOptions);
+    /** Provider id for telemetry: the adapter's (a gateway reports the upstream provider). */
+    protected providerId(): string;
+    /** How the request reaches the provider: 'direct' or 'gateway:<id>' (llm.transport). */
     protected transport(): string;
-    /** Provider-specific request body fields (merged last). */
-    /** Whether the endpoint accepts response_format json_schema (strict). */
-    protected supportsJsonSchemaFormat(): boolean;
-    /**
-     * Whether the endpoint honors stream_options.include_usage. Without it an
-     * SSE turn reports no token counts at all; Ollama and xAI both support it.
-     */
-    protected supportsStreamUsage(): boolean;
-    protected extraBodyFields(_llmRequest: LlmRequest): Record<string, unknown>;
-    /**
-     * Body fields enabling the provider's NATIVE web search, or null when the
-     * provider has none (the base then omits the tool and warns once).
-     */
-    protected webSearchBodyFields(): Record<string, unknown> | null;
-    /**
-     * Extracts reasoning from the response message. Default: "<think>" blocks
-     * in content plus the reasoning_content / reasoning fields emitted by
-     * OpenAI-compatible reasoning models.
-     */
-    protected extractReasoning(message: {
-        content?: string | null;
-        reasoning_content?: string;
-        reasoning?: string;
-    }): {
-        reasoning: string;
-        answer: string;
-    };
-    /** Yielded before the HTTP call when a precondition is missing (e.g. no
-     *  API key). Return undefined when ready to call. */
-    protected missingRequirement(): LlmResponse | undefined;
-    /** Error response for a non-2xx HTTP status. */
-    protected httpError(status: number, detail: string): LlmResponse;
-    /**
-     * Whether a turn that ended with no answer after thinking (noAnswerError)
-     * is sent once more with reasoning_effort "none". Default: never. An
-     * adapter for local reasoning models turns it on (OllamaLlm).
-     */
-    protected retriesWithoutThinking(): boolean;
-    /**
-     * Error response for a turn that produced reasoning or ran out of tokens
-     * but no reply and no tool call. `truncated` is true when the provider
-     * reported finish_reason "length" (the token budget or context window
-     * filled up); false when it stopped after thinking with nothing to say.
-     */
-    protected noAnswerError(truncated: boolean): LlmResponse;
-    /** Error response when the endpoint can't be reached at all. */
-    protected unreachable(message: string): LlmResponse;
-    generateContentAsync(llmRequest: LlmRequest, stream?: boolean): AsyncGenerator<LlmResponse, void>;
-    /**
-     * One request, retried once without thinking when the adapter opts in and
-     * the model thought its way to no answer (ADR 0027): a local reasoning
-     * model can spend its whole context window on the scratchpad. The first
-     * attempt's error is held back, never yielded; what it spent is added to
-     * the retry's usage, so budgets and the ledger still count it. An agent
-     * that already runs with reasoningEffort "none" is not retried.
-     */
-    private generateInner;
-    private attempt;
-    /**
-     * SSE path: display-only partials as the tokens land, then ONE final
-     * non-partial response carrying the complete text, tool calls and usage.
-     *
-     * WHY the final repeats text already streamed: ADK's runner persists only
-     * non-partial events (`if (!event.partial) appendEvent(...)`), so a final
-     * without text would show the reply on screen and lose it from session
-     * history. Printers therefore skip text on a turnComplete event whose
-     * partials they already rendered — see scripts/syndicate_chat.ts.
-     *
-     * Thinking is deliberately NOT carried on the final: the scratchpad is
-     * display-only and stays out of history, which is what keeps it from
-     * being replayed to the model on the next turn.
-     */
-    private streamResponse;
-    /**
-     * The one non-partial response that closes a turn, on both paths.
-     *
-     * WHY an empty reply becomes an error: ADK drops a final response with no
-     * parts and no errorCode (llm_agent: "empty content → return"), so the
-     * last event left is the thought partial — ADK logs "The last event is
-     * partial, which is not expected." and the turn ends with empty text and
-     * no reason. That is exactly what a thinking model does when its
-     * scratchpad fills the budget (finish_reason "length"): the answer never
-     * starts. Naming it lets the caller see why, and still carries the usage
-     * so the tokens spent thinking are counted.
-     *
-     * A reply that was cut short but did start keeps its text and is marked
-     * finishReason MAX_TOKENS.
-     */
-    private finalResponse;
-    /** ADK Contents (Google GenAI format) → OpenAI-compatible chat messages. */
-    protected buildMessages(llmRequest: LlmRequest): OpenAiMessage[];
-    /** ADK toolsDict → OpenAI function-tool definitions (lowercase schemas). */
+    /** The chat messages the adapter sends for this LlmRequest. */
+    protected buildMessages(llmRequest: LlmRequest): ChatMessage[];
+    /** The function tools the adapter sends for this LlmRequest (lowercase schemas). */
     protected buildTools(llmRequest: LlmRequest): unknown[];
-    /**
-     * Live/bidirectional streaming — not part of the OpenAI-compatible
-     * chat-completions surface. Throws to surface this clearly.
-     */
-    connect(_llmRequest: LlmRequest): Promise<BaseLlmConnection>;
+    /** The genai mapping's request, with the older spelling the contract leaves out. */
+    protected toModelRequest(llmRequest: LlmRequest, options: ModelRequestOptions): ChatCompletionsRequest;
+    /** The genai mapping's response, in the shape these classes have always yielded (see the header). */
+    protected toLlmResponse(response: ModelResponse): LlmResponse;
 }
 /**
  * Stamps an HTTP error response with its numeric status and whether that
- * status is transient, so callers above (and the ledger, via the tracer's
- * llm.payload.response) can tell a rate limit from a bad request without
- * parsing the message. Applied in the base so a subclass's httpError
- * override (Ollama's hint, the gateway's GATEWAY_HTTP_ERROR) keeps its
- * errorCode and wording and still gets the fields.
+ * status is transient, and the same verdict in customMetadata
+ * ('error.retryable', 'error.status'), where FallbackLlm reads it
+ * (lib/models/errorResponse.ts). The chat-completions shims take these
+ * fields from their adapter's error final instead (toLlmResponse).
  */
 export declare function withHttpStatus(resp: LlmResponse, status: number): LlmResponse;
-type Usage = NonNullable<ReturnType<typeof mapUsage>>;
-/** Two usage records summed, field by field. */
-export declare function addUsage(a: Usage | undefined, b: Usage | undefined): Usage | undefined;
+type GenaiUsage = NonNullable<ReturnType<typeof mapUsage>>;
+/** Two genai usage records summed, field by field. */
+export declare function addUsage(a: GenaiUsage | undefined, b: GenaiUsage | undefined): GenaiUsage | undefined;
+/**
+ * OpenAI-style usage → GenAI usageMetadata in the ADK-path meaning
+ * (completion_tokens, reasoning included, as candidatesTokenCount), or
+ * undefined when absent. The contract's meaning is chatUsage in
+ * lib/models/chatCompletionsAdapter.ts.
+ */
 export declare function mapUsage(usage: any): {
     promptTokenCount?: number;
     candidatesTokenCount?: number;
     thoughtsTokenCount?: number;
     totalTokenCount?: number;
 } | undefined;
-export {};