@deepstrike/sdk 0.2.52 → 0.2.61

package/dist/providers/gemini.js

@@ -1,163 +1,98 @@
 import { GoogleGenerativeAI } from "@google/generative-ai";
 import { withServerRuntimeGuard } from "../runtime/server.js";
-import { CircuitBreaker, normalizeToolCall, turnsWithStateAppended } from "./base.js";
-import { endpointProfiles } from "./profiles.js";
-import { UnsupportedModalityError } from "./base.js";
+import { CircuitBreaker } from "./base.js";
+import { endpointProfiles } from "./endpoints.js";
+import { normalizeCanonicalAdapterInput, normalizeCanonicalContext, } from "./content-normalization.js";
+import { GeminiAdapter, canonicalGeminiContents, geminiVendorConfig } from "./gemini-adapter.js";
+import { circuitOpenError, classifyProviderError } from "./provider-error.js";
 const GEMINI_BASE = endpointProfiles["gemini.google"].baseURL;
-const GEMINI_POLICIES = {
-    "gemini-3-pro-preview": { maxTurns: 50 },
-    "gemini-3-flash-preview": { maxTurns: 25 },
-    "gemini-3.5-flash": { maxTurns: 30 },
-    "gemini-2.5-pro": { maxTurns: 35 },
-    "gemini-2.5-flash": { maxTurns: 20 },
-    "gemini-2.0-flash": { maxTurns: 15 },
-    "gemini-2.0-flash-lite": { maxTurns: 10 },
-    "gemini-1.5-pro": { maxTurns: 30 },
-    "gemini-1.5-flash": { maxTurns: 15 },
-};
 export function buildContents(turns) {
-    const contents = [];
-    for (const msg of turns) {
-        if (msg.role === "tool") {
-            const parts = (msg.contentParts ?? [])
-                .filter(p => p.type === "tool_result")
-                .map(p => {
-                if (p.type !== "tool_result")
-                    return { text: "" };
-                let toolName = p.callId;
-                for (let i = turns.length - 1; i >= 0; i--) {
-                    const turn = turns[i];
-                    if (turn.role === "assistant" && turn.toolCalls) {
-                        const matched = turn.toolCalls.find(tc => tc.id === p.callId);
-                        if (matched) {
-                            toolName = matched.name;
-                            break;
-                        }
-                    }
-                }
-                return {
-                    functionResponse: { name: toolName, response: { output: p.output } },
-                };
-            });
-            if (parts.length)
-                contents.push({ role: "user", parts });
-            continue;
-        }
-        const role = msg.role === "assistant" ? "model" : "user";
-        const parts = [];
-        if (msg.toolCalls?.length) {
-            for (const tc of msg.toolCalls) {
-                let args = {};
-                try {
-                    args = JSON.parse(tc.arguments);
-                }
-                catch {
-                    args = {};
-                }
-                parts.push({ functionCall: { name: tc.name, args } });
-            }
-        }
-        // Multimodal: render contentParts (text + image) when present, else the plain
-        // text body. Without this, image inputs to Gemini were silently dropped.
-        if (msg.contentParts?.length) {
-            for (const p of msg.contentParts) {
-                if (p.type === "text")
-                    parts.push({ text: p.text });
-                else if (p.type === "image") {
-                    if (p.data)
-                        parts.push({ inlineData: { mimeType: p.mediaType ?? "image/png", data: p.data } });
-                    else if (p.url)
-                        parts.push({ fileData: { mimeType: p.mediaType ?? "image/png", fileUri: p.url } });
-                }
-                else if (p.type === "audio") {
-                    if (!p.data)
-                        throw new UnsupportedModalityError("audio", "gemini");
-                    parts.push({ inlineData: { mimeType: p.mediaType ?? "audio/wav", data: p.data } });
-                }
-                else if (p.type === "tool_result") {
-                    // tool results are handled via functionResponse on tool role messages
-                }
-                else {
-                    throw new UnsupportedModalityError(String(p.type ?? "unknown"), "gemini");
-                }
-            }
-        }
-        else if (msg.content) {
-            parts.push({ text: msg.content });
-        }
-        if (parts.length)
-            contents.push({ role, parts });
-    }
-    return contents;
-}
-function buildTools(tools) {
-    if (!tools.length)
-        return [];
-    return [{
-            functionDeclarations: tools.map(t => ({
-                name: t.name,
-                description: t.description,
-                parameters: JSON.parse(t.parameters),
-            })),
-        }];
+    return canonicalGeminiContents(normalizeCanonicalContext({ systemText: "", turns }));
 }
 export class GeminiProvider {
     model;
+    resolvedRuntime;
     genAI;
     circuit;
     maxRetries;
     baseDelay;
     requestOptions;
-    constructor(apiKey, model = "gemini-2.0-flash", retry = { maxRetries: 3, baseDelay: 1000 }, baseURL = GEMINI_BASE) {
+    resolvedRuntimePolicy;
+    adapter = new GeminiAdapter();
+    constructor(apiKey, model = "gemini-2.0-flash", retry = { maxRetries: 3, baseDelay: 1000 }, baseURL = GEMINI_BASE, runtimePolicy = {}, resolvedRuntime) {
         this.model = model;
+        this.resolvedRuntime = resolvedRuntime;
         this.genAI = withServerRuntimeGuard(() => new GoogleGenerativeAI(apiKey));
         this.circuit = new CircuitBreaker();
         this.maxRetries = retry.maxRetries;
         this.baseDelay = retry.baseDelay;
         this.requestOptions = { baseUrl: baseURL };
+        this.resolvedRuntimePolicy = runtimePolicy;
     }
     runtimePolicy() {
-        return GEMINI_POLICIES[this.model] ?? {};
+        return this.resolvedRuntimePolicy;
+    }
+    bindResolvedRuntime(resolved) {
+        if (resolved.identity.protocol !== "gemini"
+            || resolved.identity.modelId !== this.model) {
+            throw new Error("GeminiProvider received a mismatched resolved runtime");
+        }
+        this.resolvedRuntime = resolved;
+    }
+    adapterInput(context, tools, extensions) {
+        if (!this.resolvedRuntime) {
+            // Direct class construction is a published compatibility path. A-07 replaces it with
+            // injected runtime profiles; until then this local descriptor contains no Registry lookup.
+            const resolved = {
+                identity: {
+                    providerId: "gemini",
+                    modelId: this.model,
+                    endpointId: "gemini.google",
+                    protocol: "gemini",
+                },
+                model: { id: `gemini/${this.model}`, providerId: "gemini", kind: "generation", intrinsic: {} },
+                endpoint: endpointProfiles["gemini.google"],
+                adapter: this,
+                effectiveCapabilities: {
+                    inputModalities: Object.fromEntries(["text", "image", "audio", "video", "file"].map(modality => [modality, { state: modality === "video" || modality === "file" ? "unsupported" : "unknown", evidence: [] }])),
+                    outputModalities: Object.fromEntries(["text", "image", "audio", "embedding"].map(modality => [modality, { state: "unknown", evidence: [] }])),
+                    tools: { state: "unknown", evidence: [] },
+                    reasoning: { state: "unknown", evidence: [] },
+                    parallelToolCalls: { state: "unknown", evidence: [] },
+                    structuredOutput: { state: "unknown", evidence: [] },
+                    promptCaching: { state: "unknown", evidence: [] },
+                    nativeTokenCounting: { state: "unknown", evidence: [] },
+                    mediaForms: Object.fromEntries(["imageUrl", "imageBase64", "fileId", "audioUrl", "audioBase64"].map(form => [form, { state: "unknown", evidence: [] }])),
+                },
+            };
+            return normalizeCanonicalAdapterInput({ context, tools, resolved, extensions });
+        }
+        return normalizeCanonicalAdapterInput({
+            context,
+            tools,
+            resolved: this.resolvedRuntime,
+            extensions,
+        });
     }
     async complete(context, tools, extensions) {
         if (this.circuit.isOpen())
-            throw new Error("Circuit breaker open");
-        const system = context.systemText || undefined;
-        const contents = buildContents(turnsWithStateAppended(context));
-        const geminiTools = buildTools(tools);
+            throw circuitOpenError("gemini");
+        let input;
+        let plan;
+        try {
+            input = this.adapterInput(context, tools, extensions);
+            plan = this.adapter.buildRequest(input);
+        }
+        catch (error) {
+            throw classifyProviderError("gemini", error);
+        }
         let lastErr;
         for (let i = 0; i < this.maxRetries; i++) {
             try {
-                const vc = this.vendorConfig(extensions);
-                const allTools = [...geminiTools, ...(vc.tools ?? [])];
-                const m = this.genAI.getGenerativeModel({
-                    ...this.modelExtensions(extensions),
-                    model: this.model,
-                    ...(system ? { systemInstruction: system } : {}),
-                    ...(allTools.length ? { tools: allTools } : {}),
-                    ...(vc.generationConfig ? { generationConfig: vc.generationConfig } : {}),
-                }, this.requestOptions);
-                const resp = await m.generateContent({ contents });
+                const m = this.genAI.getGenerativeModel(plan.modelParams, this.requestOptions);
+                const resp = await m.generateContent(plan.request);
                 this.circuit.recordSuccess();
-                const candidate = resp.response.candidates?.[0];
-                let content = "";
-                const toolCalls = [];
-                for (const part of candidate?.content.parts ?? []) {
-                    if (part.text)
-                        content += part.text;
-                    else if (part.functionCall) {
-                        const tc = normalizeToolCall(part.functionCall.name, part.functionCall.name, part.functionCall.args);
-                        if (tc)
-                            toolCalls.push(tc);
-                    }
-                }
-                const usage = resp.response.usageMetadata;
-                return {
-                    role: "assistant",
-                    content,
-                    tokenCount: usage?.candidatesTokenCount ?? usage?.totalTokenCount,
-                    toolCalls,
-                };
+                return this.adapter.decodeComplete(resp.response, { input }).message;
             }
             catch (err) {
                 lastErr = err;
@@ -166,60 +101,40 @@ export class GeminiProvider {
                     await new Promise(r => setTimeout(r, this.baseDelay * 2 ** i));
             }
         }
-        throw lastErr;
+        throw classifyProviderError("gemini", lastErr);
     }
     async *stream(context, tools, extensions) {
-        const system = context.systemText || undefined;
-        const contents = buildContents(turnsWithStateAppended(context));
-        const geminiTools = buildTools(tools);
-        const vc = this.vendorConfig(extensions);
-        const allTools = [...geminiTools, ...(vc.tools ?? [])];
-        const m = this.genAI.getGenerativeModel({
-            ...this.modelExtensions(extensions),
-            model: this.model,
-            ...(system ? { systemInstruction: system } : {}),
-            ...(allTools.length ? { tools: allTools } : {}),
-            ...(vc.generationConfig ? { generationConfig: vc.generationConfig } : {}),
-        }, this.requestOptions);
-        const result = await m.generateContentStream({ contents });
-        const toolCalls = [];
-        for await (const chunk of result.stream) {
-            for (const part of chunk.candidates?.[0]?.content.parts ?? []) {
-                if (part.text)
-                    yield { type: "text_delta", delta: part.text };
-                else if (part.functionCall) {
-                    const { name, args } = part.functionCall;
-                    toolCalls.push({ id: `call_${toolCalls.length + 1}`, name, args: args });
-                }
+        try {
+            const input = this.adapterInput(context, tools, extensions);
+            const plan = this.adapter.buildRequest(input);
+            const m = this.genAI.getGenerativeModel(plan.modelParams, this.requestOptions);
+            const result = await m.generateContentStream(plan.request);
+            const state = this.adapter.createStreamState({ input });
+            for await (const chunk of result.stream) {
+                for (const event of this.adapter.pushStreamChunk(chunk, state).events)
+                    yield event;
             }
+            for (const event of this.adapter.finishStream(state, await result.response).events)
+                yield event;
         }
-        for (const tc of toolCalls) {
-            yield { type: "tool_call", id: tc.id, name: tc.name, arguments: tc.args };
-        }
-        const usage = (await result.response).usageMetadata;
-        if (usage?.totalTokenCount) {
-            // Gemini implicit/explicit cache hits are reported as cachedContentTokenCount,
-            // a subset of promptTokenCount (which stays the full prompt for accounting).
-            const cachedTokens = usage.cachedContentTokenCount ?? 0;
-            yield {
-                type: "usage",
-                totalTokens: usage.totalTokenCount,
-                inputTokens: usage.promptTokenCount ?? 0,
-                outputTokens: usage.candidatesTokenCount ?? 0,
-                ...(cachedTokens > 0 ? { cacheReadInputTokens: cachedTokens } : {}),
-            };
+        catch (error) {
+            throw classifyProviderError("gemini", error);
         }
     }
-    modelExtensions(extensions) {
-        if (!extensions)
-            return {};
-        // Strip keys handled explicitly elsewhere (incl. the vendor server-tool / structured-output keys
-        // consumed by `vendorConfig`) so they never leak raw into getGenerativeModel.
-        // Strip keys handled explicitly: the SDK fields set below + the named vendor keys consumed by
-        // `vendorConfig`. A caller-provided raw `generationConfig` still passes through (and is merged with
-        // any structured-output config at the call site).
-        const { model: _model, systemInstruction: _systemInstruction, tools: _tools, google_search: _gs, response_mime_type: _rmt, response_schema: _rs, ...rest } = extensions;
-        return rest;
+    /**
+     * spc_011-C-05: preflight native token count via `GenerativeModel.countTokens` — reuses the
+     * same contents/tools/vendorConfig construction `complete()` uses so the counted request and
+     * the sent request never diverge.
+     */
+    async countTokens(context, tools, extensions) {
+        const plan = this.adapter.buildRequest(this.adapterInput(context, tools, extensions));
+        const m = this.genAI.getGenerativeModel(plan.modelParams, this.requestOptions);
+        const resp = await m.countTokens(plan.request);
+        return {
+            inputTokens: resp.totalTokens,
+            source: { kind: "native", provider: "gemini" },
+            confidence: "exact",
+        };
     }
     /**
      * Gemini vendor features from extensions, mapped to the Node SDK shape (mirrors the Python provider's
@@ -230,19 +145,6 @@ export class GeminiProvider {
      *    pairing this with google_search).
      */
     vendorConfig(extensions) {
-        const ext = extensions ?? {};
-        const tools = [];
-        if (ext.google_search)
-            tools.push({ googleSearch: typeof ext.google_search === "object" ? ext.google_search : {} });
-        // Seed from any caller-provided raw generationConfig, then layer the named structured-output keys.
-        const gc = { ...ext.generationConfig };
-        if (ext.response_mime_type != null)
-            gc.responseMimeType = ext.response_mime_type;
-        if (ext.response_schema != null)
-            gc.responseSchema = ext.response_schema;
-        return {
-            ...(tools.length ? { tools } : {}),
-            ...(Object.keys(gc).length ? { generationConfig: gc } : {}),
-        };
+        return geminiVendorConfig(extensions ?? {});
     }
 }

package/dist/providers/model-catalog.d.ts

@@ -0,0 +1,37 @@
+import type { ModelRegistration } from "./model-registry.js";
+export type { ModelRegistration } from "./model-registry.js";
+/** A query-only model catalog. Catalogs describe models; selection policy belongs to CapabilityRouter. */
+export interface ModelCatalog {
+    list(): Promise<readonly ModelRegistration[]>;
+    get(modelId: string): Promise<ModelRegistration | undefined>;
+}
+export interface ModelCatalogSource {
+    list(): Promise<readonly ModelRegistration[]>;
+}
+export type ModelCatalogRefreshResult = {
+    ok: true;
+} | {
+    ok: false;
+    errorCode: "refresh_failed";
+};
+/** Immutable, deterministic model facts supplied by the SDK or an application. */
+export declare class StaticModelCatalog implements ModelCatalog {
+    private readonly registrations;
+    private readonly byId;
+    constructor(registrations: readonly ModelRegistration[]);
+    list(): Promise<readonly ModelRegistration[]>;
+    get(modelId: string): Promise<ModelRegistration | undefined>;
+}
+/**
+ * A host-owned discovery cache. Refresh never throws and never deletes the last good snapshot;
+ * callers can keep using the static catalog when a remote provider is unavailable.
+ */
+export declare class DynamicModelCatalog implements ModelCatalog {
+    private readonly source;
+    private readonly fallback;
+    private snapshot;
+    constructor(source: ModelCatalogSource, fallback?: ModelCatalog);
+    list(): Promise<readonly ModelRegistration[]>;
+    get(modelId: string): Promise<ModelRegistration | undefined>;
+    refresh(): Promise<ModelCatalogRefreshResult>;
+}

package/dist/providers/model-catalog.js

@@ -0,0 +1,62 @@
+/** Immutable, deterministic model facts supplied by the SDK or an application. */
+export class StaticModelCatalog {
+    registrations;
+    byId;
+    constructor(registrations) {
+        const byId = new Map();
+        for (const registration of registrations) {
+            const id = registration.descriptor.id;
+            if (byId.has(id))
+                throw new Error(`Duplicate model catalog entry: ${id}`);
+            byId.set(id, registration);
+        }
+        this.registrations = [...byId.values()].sort((a, b) => a.descriptor.id.localeCompare(b.descriptor.id));
+        this.byId = byId;
+    }
+    async list() {
+        return this.registrations;
+    }
+    async get(modelId) {
+        return this.byId.get(modelId);
+    }
+}
+/**
+ * A host-owned discovery cache. Refresh never throws and never deletes the last good snapshot;
+ * callers can keep using the static catalog when a remote provider is unavailable.
+ */
+export class DynamicModelCatalog {
+    source;
+    fallback;
+    snapshot = new Map();
+    constructor(source, fallback = new StaticModelCatalog([])) {
+        this.source = source;
+        this.fallback = fallback;
+    }
+    async list() {
+        const merged = new Map();
+        for (const registration of await this.fallback.list())
+            merged.set(registration.descriptor.id, registration);
+        for (const registration of this.snapshot.values())
+            merged.set(registration.descriptor.id, registration);
+        return [...merged.values()].sort((a, b) => a.descriptor.id.localeCompare(b.descriptor.id));
+    }
+    async get(modelId) {
+        return this.snapshot.get(modelId) ?? await this.fallback.get(modelId);
+    }
+    async refresh() {
+        try {
+            const next = new Map();
+            for (const registration of await this.source.list()) {
+                const id = registration.descriptor.id;
+                if (next.has(id))
+                    throw new Error("duplicate dynamic model catalog entry");
+                next.set(id, registration);
+            }
+            this.snapshot = next;
+            return { ok: true };
+        }
+        catch {
+            return { ok: false, errorCode: "refresh_failed" };
+        }
+    }
+}

package/dist/providers/model-registry.d.ts

@@ -0,0 +1,119 @@
+import type { LLMProvider, RuntimePolicy } from "../types.js";
+import { type EndpointProfile, type EndpointProfileId, type EndpointProtocol, type ProviderId } from "./endpoints.js";
+import { type GenerationProtocol, type InputModality, type OutputModality, type ProtocolRuntimeCapabilities, type ProtocolRuntimeCapabilityOverrides } from "./protocol-capabilities.js";
+export type { GenerationProtocol, InputModality, OutputModality, ProtocolRuntimeCapabilities, ProtocolRuntimeCapabilityOverrides, } from "./protocol-capabilities.js";
+export type ModelKind = "generation" | "embedding";
+export type CapabilityState = "supported" | "unsupported" | "unknown";
+export declare const MODEL_CAPABILITY_STATES: readonly CapabilityState[];
+export interface ModelDescriptor {
+    id: string;
+    providerId: string;
+    kind: ModelKind;
+    contextWindow?: number;
+    maxOutputTokens?: number;
+    intrinsic: {
+        inputModalities?: readonly InputModality[];
+        outputModalities?: readonly OutputModality[];
+        tools?: boolean;
+        reasoning?: boolean;
+    };
+}
+export interface ModelRegistration {
+    descriptor: ModelDescriptor;
+    defaultEndpointId: EndpointProfileId;
+    recommendedRuntimePolicy?: RuntimePolicy;
+}
+export interface DynamicModelDescriptorResolver {
+    readonly providerId: ProviderId;
+    resolve(modelId: string): ModelRegistration;
+}
+export interface EndpointRuntimeCapabilities {
+    nativeTokenCounting?: boolean;
+    promptCaching?: boolean;
+    protocolOverrides?: ProtocolRuntimeCapabilityOverrides;
+}
+export interface CacheCapabilityEvidence {
+    endpointId: EndpointProfileId;
+    source: string;
+    verifiedAt: "2026-08-26";
+    classification: "documentation" | "live_probe";
+    usageFields: readonly string[];
+}
+export interface TokenMeasurementEvidence {
+    endpointId: EndpointProfileId;
+    source: string;
+    verifiedAt: "2026-08-26";
+    providerApiState: "supported" | "unsupported" | "unknown";
+    adapterState: "available" | "unavailable";
+    method: "provider_preflight" | "official_local_tokenizer" | "postflight" | "heuristic";
+    coverage: readonly string[];
+    sdk: string;
+}
+export type CapabilityEvidenceLayer = "model" | "protocol" | "endpoint";
+export interface EffectiveCapability<T = boolean> {
+    state: CapabilityState;
+    value?: T;
+    evidence: readonly CapabilityEvidenceLayer[];
+}
+export interface EffectiveModelCapabilities {
+    inputModalities: Record<InputModality, EffectiveCapability>;
+    outputModalities: Record<OutputModality, EffectiveCapability>;
+    tools: EffectiveCapability;
+    reasoning: EffectiveCapability;
+    parallelToolCalls: EffectiveCapability;
+    structuredOutput: EffectiveCapability;
+    promptCaching: EffectiveCapability;
+    nativeTokenCounting: EffectiveCapability;
+    mediaForms: {
+        imageUrl: EffectiveCapability;
+        imageBase64: EffectiveCapability;
+        fileId: EffectiveCapability;
+        audioUrl: EffectiveCapability;
+        audioBase64: EffectiveCapability;
+    };
+}
+export interface ResolvedProviderRuntime<TAdapter = LLMProvider> {
+    identity: {
+        providerId: ProviderId;
+        modelId: string;
+        endpointId: EndpointProfileId;
+        protocol: GenerationProtocol;
+    };
+    model: ModelDescriptor;
+    endpoint: EndpointProfile;
+    adapter: TAdapter;
+    effectiveCapabilities: EffectiveModelCapabilities;
+    runtimePolicy?: RuntimePolicy;
+}
+export interface RegistryRuleEvidence {
+    ruleId: string;
+    classification: "routing" | "policy" | "protocol" | "endpoint";
+    source: string;
+    verifiedAt: "2026-08-12";
+}
+export declare const registryEvidence: readonly RegistryRuleEvidence[];
+export declare const cacheCapabilityEvidence: readonly CacheCapabilityEvidence[];
+export declare const tokenMeasurementEvidence: readonly TokenMeasurementEvidence[];
+export declare function defaultModelForProvider(providerId: ProviderId): string;
+export declare function defaultEndpointForProvider(providerId: ProviderId): EndpointProfileId;
+export declare class ModelRegistry {
+    resolve(modelId: string, providerId?: ProviderId): ModelRegistration | undefined;
+}
+export declare const modelRegistry: ModelRegistry;
+export declare function normalizeModelId(providerId: string, modelId: string): string;
+export declare function getRuntimePolicy(providerId: string, modelId: string): RuntimePolicy;
+export declare const protocolRuntimeCapabilities: Record<GenerationProtocol, ProtocolRuntimeCapabilities>;
+export declare const endpointRuntimeCapabilities: Partial<Record<EndpointProfileId, EndpointRuntimeCapabilities>>;
+export declare function resolveEffectiveCapability<T = boolean>(layers: readonly {
+    layer: CapabilityEvidenceLayer;
+    state: CapabilityState;
+    value?: T;
+}[]): EffectiveCapability<T>;
+export declare function resolveEffectiveModelCapabilities(input: {
+    model: ModelDescriptor;
+    protocol: GenerationProtocol;
+    endpointCapabilities?: EndpointRuntimeCapabilities;
+}): EffectiveModelCapabilities;
+export declare function generationProtocol(protocol: EndpointProtocol): GenerationProtocol | undefined;
+export declare function endpointCapabilitiesFor(endpointId: EndpointProfileId, preserveEndpointIdentity: boolean, preserveCacheEvidence?: boolean): EndpointRuntimeCapabilities | undefined;
+export declare function isKnownProviderId(value: string): value is ProviderId;