@deepstrike/sdk 0.2.52 → 0.2.61

package/dist/providers/base.d.ts

@@ -18,8 +18,8 @@ export declare const INTERNAL_EXTENSION_KEYS: readonly string[];
 export declare function omitExtensionKeys(extensions: Record<string, unknown> | undefined, keys: readonly string[]): Record<string, unknown>;
 /**
  * Cached-prompt-token count from an OpenAI-compatible usage object. Covers the
- * standard `prompt_tokens_details.cached_tokens` (OpenAI, Qwen, MiniMax, GLM,
- * Kimi) and DeepSeek's `prompt_cache_hit_tokens`. These caches bill reads only,
+ * Chat `prompt_tokens_details.cached_tokens`, Responses
+ * `input_tokens_details.cached_tokens`, and DeepSeek's `prompt_cache_hit_tokens`. These caches bill reads only,
  * so there is no separate cache-creation count. The figure is a subset of
  * `prompt_tokens` (the full prompt), surfaced for cost visibility — it must not
  * be subtracted from the input count the kernel uses for context accounting.

package/dist/providers/base.js

@@ -1,3 +1,4 @@
+import { normalizeToolResultPart, projectToolOutputToText } from "./content-normalization.js";
 export class CircuitBreaker {
     openAfter;
     resetAfter;
@@ -43,8 +44,8 @@ export function omitExtensionKeys(extensions, keys) {
 }
 /**
  * Cached-prompt-token count from an OpenAI-compatible usage object. Covers the
- * standard `prompt_tokens_details.cached_tokens` (OpenAI, Qwen, MiniMax, GLM,
- * Kimi) and DeepSeek's `prompt_cache_hit_tokens`. These caches bill reads only,
+ * Chat `prompt_tokens_details.cached_tokens`, Responses
+ * `input_tokens_details.cached_tokens`, and DeepSeek's `prompt_cache_hit_tokens`. These caches bill reads only,
  * so there is no separate cache-creation count. The figure is a subset of
  * `prompt_tokens` (the full prompt), surfaced for cost visibility — it must not
  * be subtracted from the input count the kernel uses for context accounting.
@@ -53,10 +54,12 @@ export function openAICachedPromptTokens(usage) {
     if (!usage || typeof usage !== "object")
         return 0;
     const u = usage;
-    const details = u.prompt_tokens_details;
-    const standard = typeof details?.cached_tokens === "number" ? details.cached_tokens : 0;
+    const promptDetails = u.prompt_tokens_details;
+    const inputDetails = u.input_tokens_details;
+    const standard = typeof promptDetails?.cached_tokens === "number" ? promptDetails.cached_tokens : 0;
+    const responses = typeof inputDetails?.cached_tokens === "number" ? inputDetails.cached_tokens : 0;
     const deepseek = typeof u.prompt_cache_hit_tokens === "number" ? u.prompt_cache_hit_tokens : 0;
-    return Math.max(standard, deepseek);
+    return Math.max(standard, responses, deepseek);
 }
 /**
  * Prompt-cache hit rate for one usage record: the fraction of the full prompt
@@ -140,11 +143,40 @@ export function toAnthropicContent(msg) {
             throw new UnsupportedModalityError("audio", "anthropic");
         }
         if (p.type === "tool_result") {
-            return { type: "tool_result", tool_use_id: p.callId, content: p.output, is_error: p.isError };
+            return { type: "tool_result", tool_use_id: p.callId, content: toolResultAnthropicContent(p), is_error: p.isError };
         }
         return { type: "text", text: "" };
     });
 }
+/**
+ * spc_012-N-03: a `ContentBlock` inside a structured tool result → Anthropic wire block.
+ * Anthropic's `tool_result.content` natively accepts text and image blocks. Anything else
+ * (audio/video/file, `fileId`/`object` sources with no Anthropic wire form) degrades to an
+ * explicit `[modality]` placeholder visible to the model, never silently dropped (INV-012-01).
+ */
+function contentBlockToAnthropic(block) {
+    if (block.type === "text")
+        return { type: "text", text: block.text };
+    if (block.type === "image") {
+        const src = block.source;
+        if (src.kind === "base64") {
+            return { type: "image", source: { type: "base64", media_type: block.mediaType ?? "image/png", data: src.data } };
+        }
+        if (src.kind === "url") {
+            return { type: "image", source: { type: "url", url: src.url } };
+        }
+        return { type: "text", text: "[image]" };
+    }
+    return { type: "text", text: `[${block.type}]` };
+}
+/**
+ * Structured `contentParts` win when present; otherwise `output` is the text form.
+ */
+function toolResultAnthropicContent(p) {
+    if (p.contentParts !== undefined)
+        return normalizeToolResultPart(p).blocks.map(contentBlockToAnthropic);
+    return p.output;
+}
 /**
  * History turns with the volatile State turn appended as the latest turn, for
  * providers that render it inline (OpenAI-family, Gemini, Ollama). Appending
@@ -166,7 +198,7 @@ export function toAnthropicMessages(turns, nativeReplay) {
         if (msg.role === "tool") {
             const parts = (msg.contentParts ?? [])
                 .filter((p) => p.type === "tool_result")
-                .map(p => ({ type: "tool_result", tool_use_id: p.callId, content: p.output, is_error: p.isError }));
+                .map(p => ({ type: "tool_result", tool_use_id: p.callId, content: toolResultAnthropicContent(p), is_error: p.isError }));
             if (parts.length)
                 result.push({ role: "user", content: parts });
             continue;
@@ -246,10 +278,20 @@ export function toOpenAIMessageParams(context) {
     // bindings, where the state is already inside `turns`.
     for (const msg of turnsWithStateAppended(context)) {
         if (msg.role === "tool") {
+            // spc_012-N-04: OpenAI **chat completions** tool-role messages accept text only — no
+            // structured tool_result content exists on this wire. Explicit text-only degradation:
+            // `output` is the constructor's text projection, which carries a visible `[modality]`
+            // placeholder for any structured block (INV-012-01 — degraded, not silently dropped).
+            // The Responses API (openai-responses.ts) does have native structured support and uses it.
             const parts = (msg.contentParts ?? [])
                 .filter((p) => p.type === "tool_result");
             for (const p of parts) {
-                result.push({ role: "tool", tool_call_id: p.callId, content: p.output });
+                const canonical = normalizeToolResultPart(p);
+                result.push({
+                    role: "tool",
+                    tool_call_id: p.callId,
+                    content: projectToolOutputToText(canonical.blocks),
+                });
             }
             continue;
         }

package/dist/providers/capability-router.d.ts

@@ -0,0 +1,29 @@
+import type { CreateProviderOptions } from "./catalog.js";
+import type { InputModality, ResolvedProviderRuntime } from "./model-registry.js";
+export interface CapabilityRequirement {
+    requiredInputModalities?: readonly InputModality[];
+    tools?: boolean;
+    reasoning?: boolean;
+    minimumContextWindow?: number;
+}
+export type CapabilityRouteResult = {
+    ok: true;
+    runtime: ResolvedProviderRuntime;
+} | {
+    ok: false;
+    error: {
+        code: "no_capable_model";
+        requirement: CapabilityRequirement;
+        candidates: Array<{
+            model: string;
+            rejectedBy: string[];
+        }>;
+    };
+};
+/**
+ * Deliberately policy-free first-match router. Unknown capability evidence stays eligible for
+ * forward compatibility; only evidence of unsupported capability rejects a candidate.
+ */
+export declare class CapabilityRouter {
+    route(requirement: CapabilityRequirement, candidates: readonly CreateProviderOptions[]): Promise<CapabilityRouteResult>;
+}

package/dist/providers/capability-router.js

@@ -0,0 +1,43 @@
+import { resolveProviderRuntimeAsync } from "./catalog.js";
+/**
+ * Deliberately policy-free first-match router. Unknown capability evidence stays eligible for
+ * forward compatibility; only evidence of unsupported capability rejects a candidate.
+ */
+export class CapabilityRouter {
+    async route(requirement, candidates) {
+        const rejected = [];
+        for (const candidate of candidates) {
+            let runtime;
+            try {
+                runtime = await resolveProviderRuntimeAsync(candidate);
+            }
+            catch {
+                rejected.push({ model: candidate.model, rejectedBy: ["unavailable"] });
+                continue;
+            }
+            const rejectedBy = rejects(requirement, runtime);
+            if (rejectedBy.length === 0)
+                return { ok: true, runtime };
+            rejected.push({ model: candidate.model, rejectedBy });
+        }
+        return { ok: false, error: { code: "no_capable_model", requirement, candidates: rejected } };
+    }
+}
+function rejects(requirement, runtime) {
+    const result = [];
+    for (const modality of requirement.requiredInputModalities ?? []) {
+        if (runtime.effectiveCapabilities.inputModalities[modality].state === "unsupported") {
+            result.push(`input:${modality}`);
+        }
+    }
+    if (requirement.tools && runtime.effectiveCapabilities.tools.state === "unsupported")
+        result.push("tools");
+    if (requirement.reasoning && runtime.effectiveCapabilities.reasoning.state === "unsupported")
+        result.push("reasoning");
+    if (requirement.minimumContextWindow !== undefined
+        && runtime.model.contextWindow !== undefined
+        && runtime.model.contextWindow < requirement.minimumContextWindow) {
+        result.push("context");
+    }
+    return result;
+}

package/dist/providers/catalog.d.ts

@@ -1,9 +1,17 @@
 import type { LLMProvider } from "../types.js";
-import { endpointProfiles, type ModelProfileId, type ProviderId } from "./profiles.js";
-export type EndpointProfileId = keyof typeof endpointProfiles;
+import { type ResolvedProviderRuntime } from "./model-registry.js";
+import { type EndpointProfileId, type ProviderId } from "./endpoints.js";
+import { type CredentialOptions } from "./credentials.js";
+import type { ModelCatalog } from "./model-catalog.js";
+export type { EndpointProfileId } from "./endpoints.js";
 export interface CreateProviderOptions {
-    model: ModelProfileId | string;
-    apiKey: string;
+    model: string;
+    /** Explicit credential; resolver-backed construction can omit it. */
+    apiKey?: string;
+    bearerToken?: string;
+    credentialResolver?: CredentialOptions["credentialResolver"];
+    /** Host-provided catalog used only for lookup; it never carries routing policy. */
+    modelCatalog?: ModelCatalog;
     provider?: ProviderId;
     endpoint?: EndpointProfileId;
     retry?: {
@@ -13,3 +21,7 @@ export interface CreateProviderOptions {
     baseURL?: string;
 }
 export declare function createProvider(options: CreateProviderOptions): LLMProvider;
+export declare function resolveProviderRuntime(options: CreateProviderOptions): ResolvedProviderRuntime;
+/** I/O-capable equivalent for host credential resolvers and dynamic catalogs. */
+export declare function resolveProviderRuntimeAsync(options: CreateProviderOptions): Promise<ResolvedProviderRuntime>;
+export declare function createProviderAsync(options: CreateProviderOptions): Promise<LLMProvider>;

package/dist/providers/catalog.js

@@ -1,9 +1,46 @@
-import { PROVIDER_REGISTRY, providerRegistryKey } from "./registry.js";
-import { endpointProfiles, getModelProfile, modelProfiles } from "./profiles.js";
+import { PROVIDER_REGISTRY, providerRegistryKey, supportsBearerCredential } from "./registry.js";
+import { defaultEndpointForProvider, endpointCapabilitiesFor, generationProtocol, modelRegistry, normalizeModelId, resolveEffectiveModelCapabilities, } from "./model-registry.js";
+import { endpointProfiles } from "./endpoints.js";
+import { resolveCredential, resolveCredentialSync, CredentialResolutionError, } from "./credentials.js";
 export function createProvider(options) {
-    const profile = isModelProfileId(options.model) ? getModelProfile(options.model) : undefined;
+    return resolveProviderRuntime(options).adapter;
+}
+export function resolveProviderRuntime(options) {
+    const draft = resolveRuntimeDraft(options);
+    const credential = draft.providerId === "ollama"
+        ? { type: "api_key", value: "" }
+        : resolveCredentialSync(draft.credentialRequest, options);
+    return constructResolvedRuntime(draft, credential, options);
+}
+/** I/O-capable equivalent for host credential resolvers and dynamic catalogs. */
+export async function resolveProviderRuntimeAsync(options) {
+    const draft = await resolveRuntimeDraftAsync(options);
+    const credential = draft.providerId === "ollama"
+        ? { type: "api_key", value: "" }
+        : await resolveCredential(draft.credentialRequest, options);
+    return constructResolvedRuntime(draft, credential, options);
+}
+export async function createProviderAsync(options) {
+    return (await resolveProviderRuntimeAsync(options)).adapter;
+}
+function resolveRuntimeDraft(options) {
     const parsedProviderId = providerPrefix(options.model);
-    const endpointId = (options.endpoint ?? profile?.defaultEndpointId ?? defaultEndpointForProvider(options.provider ?? parsedProviderId));
+    const providerHint = options.provider ?? parsedProviderId;
+    const initialRegistration = modelRegistry.resolve(options.model, providerHint);
+    return resolveRuntimeDraftWithRegistration(options, parsedProviderId, initialRegistration);
+}
+async function resolveRuntimeDraftAsync(options) {
+    const parsedProviderId = providerPrefix(options.model);
+    const providerHint = options.provider ?? parsedProviderId;
+    const fromCatalog = options.modelCatalog ? await options.modelCatalog.get(options.model) : undefined;
+    const initialRegistration = fromCatalog ?? modelRegistry.resolve(options.model, providerHint);
+    return resolveRuntimeDraftWithRegistration(options, parsedProviderId, initialRegistration);
+}
+function resolveRuntimeDraftWithRegistration(options, parsedProviderId, initialRegistration) {
+    const providerHint = options.provider ?? parsedProviderId;
+    const endpointId = (options.endpoint
+        ?? initialRegistration?.defaultEndpointId
+        ?? (providerHint ? defaultEndpointForProvider(providerHint) : undefined));
     if (!endpointId) {
         throw new Error(`Unknown model profile: ${options.model}. Pass provider or endpoint for custom model names.`);
     }
@@ -11,26 +48,84 @@ export function createProvider(options) {
     if (!endpoint) {
         throw new Error(`Unknown endpoint profile: ${endpointId}`);
     }
-    const providerId = profile?.providerId ?? options.provider ?? parsedProviderId ?? endpoint.providerId;
-    if (profile && options.provider && options.provider !== profile.providerId) {
-        throw new Error(`Model ${profile.id} belongs to provider ${profile.providerId}, not ${options.provider}`);
-    }
+    const providerId = (initialRegistration?.descriptor.providerId ?? options.provider ?? parsedProviderId ?? endpoint.providerId);
+    const registration = initialRegistration ?? modelRegistry.resolve(options.model, providerId);
+    if (!registration)
+        throw new Error(`Unable to resolve model ${options.model} for provider ${providerId}`);
     if (parsedProviderId && options.provider && parsedProviderId !== options.provider) {
         throw new Error(`Model ${options.model} uses provider prefix ${parsedProviderId}, not ${options.provider}`);
     }
     if (endpoint.providerId !== providerId) {
         throw new Error(`Endpoint ${endpoint.id} does not belong to provider ${providerId}`);
     }
-    const model = modelNameForProvider(options.model, providerId);
-    const baseURL = options.baseURL ?? endpoint.baseURL;
-    // Single data-driven dispatch: one registry keyed by (providerId, protocol).
-    const make = PROVIDER_REGISTRY[providerRegistryKey(providerId, endpoint.protocol)];
-    if (make)
-        return make(options.apiKey, model, options.retry, baseURL);
-    throw new Error(`No Node provider factory for ${options.model} on ${endpoint.id}`);
+    const model = normalizeModelId(providerId, options.model);
+    return {
+        providerId,
+        model,
+        endpointId,
+        endpoint,
+        registration,
+        credentialRequest: { providerId, modelId: model, endpointId, protocol: endpoint.protocol },
+    };
+}
+function constructResolvedRuntime(draft, credential, options) {
+    if (credential.type === "bearer" && !supportsBearerCredential(draft.providerId, draft.endpoint.protocol)) {
+        throw new CredentialResolutionError("credential_auth_mode_unsupported", draft.providerId);
+    }
+    const make = PROVIDER_REGISTRY[providerRegistryKey(draft.providerId, draft.endpoint.protocol)];
+    if (!make)
+        throw new Error(`No Node provider factory for ${draft.model} on ${draft.endpoint.id}`);
+    const protocol = generationProtocol(draft.endpoint.protocol);
+    if (!protocol)
+        throw new Error(`No Node provider factory for ${draft.model} on ${draft.endpoint.id}`);
+    const adapter = make(credential.value, draft.model, options.retry, options.baseURL ?? draft.endpoint.baseURL, draft.registration.recommendedRuntimePolicy, credential.type);
+    const resolved = {
+        identity: { providerId: draft.providerId, modelId: draft.model, endpointId: draft.endpointId, protocol },
+        model: draft.registration.descriptor,
+        endpoint: draft.endpoint,
+        adapter,
+        effectiveCapabilities: resolveEffectiveModelCapabilities({
+            model: draft.registration.descriptor,
+            protocol,
+            endpointCapabilities: endpointCapabilitiesFor(draft.endpointId, options.baseURL === undefined || options.endpoint !== undefined, options.baseURL === undefined),
+        }),
+        ...(draft.registration.recommendedRuntimePolicy ? { runtimePolicy: draft.registration.recommendedRuntimePolicy } : {}),
+    };
+    const bind = adapter.bindResolvedRuntime;
+    bind?.call(adapter, resolved);
+    const requestPlanIdentity = {
+        providerId: resolved.identity.providerId,
+        modelId: resolved.identity.modelId,
+        endpoint: {
+            id: resolved.identity.endpointId,
+            protocol: resolved.identity.protocol,
+            baseURL: safeEndpointBaseURL(options.baseURL ?? draft.endpoint.baseURL),
+        },
+        ...(resolved.effectiveCapabilities.nativeTokenCounting.state === "supported"
+            && resolved.effectiveCapabilities.nativeTokenCounting.value === true
+            ? { nativeTokenCounting: true }
+            : {}),
+    };
+    adapter
+        .requestPlanIdentity = () => ({
+        ...requestPlanIdentity,
+        endpoint: { ...requestPlanIdentity.endpoint },
+    });
+    return resolved;
 }
-function isModelProfileId(model) {
-    return Object.prototype.hasOwnProperty.call(modelProfiles, model);
+function safeEndpointBaseURL(baseURL) {
+    try {
+        const parsed = new URL(baseURL);
+        parsed.username = "";
+        parsed.password = "";
+        parsed.search = "";
+        parsed.hash = "";
+        return parsed.toString().replace(/\/$/, "");
+    }
+    catch {
+        // Provider construction has already accepted this opaque endpoint. Do not invent a replacement.
+        return baseURL;
+    }
 }
 function providerPrefix(model) {
     const [prefix] = model.split("/", 1);
@@ -39,22 +134,3 @@ function providerPrefix(model) {
 function providerIds() {
     return Array.from(new Set(Object.values(endpointProfiles).map(endpoint => endpoint.providerId)));
 }
-function defaultEndpointForProvider(providerId) {
-    if (!providerId)
-        return undefined;
-    const defaults = {
-        anthropic: "anthropic.messages",
-        openai: "openai.chat",
-        minimax: "minimax.anthropic",
-        deepseek: "deepseek.anthropic",
-        kimi: "kimi.anthropic",
-        qwen: "qwen.anthropic",
-        gemini: "gemini.google",
-        glm: "glm.anthropic",
-    };
-    return defaults[providerId];
-}
-function modelNameForProvider(model, providerId) {
-    const prefix = `${providerId}/`;
-    return model.startsWith(prefix) ? model.slice(prefix.length) : model;
-}

package/dist/providers/content-normalization.d.ts

@@ -0,0 +1,57 @@
+import type { Message, RenderedContext, ToolOutputBlock, ToolResultPart, ToolSchema, ToolCall, ProviderReplay } from "../types.js";
+import type { ResolvedProviderRuntime } from "./model-registry.js";
+export declare class ContentValidationError extends Error {
+    constructor(message: string);
+}
+export declare class ToolResultProjectionConflictError extends ContentValidationError {
+    constructor(callId: string);
+}
+export interface CanonicalToolResult {
+    readonly type: "tool_result";
+    readonly callId: string;
+    readonly blocks: readonly ToolOutputBlock[];
+    readonly isError: boolean;
+    /** Preserves the caller's explicit text-vs-block wire intent without duplicating content. */
+    readonly contentForm?: "text" | "blocks";
+}
+export type CanonicalMessageBlock = ToolOutputBlock | CanonicalToolResult;
+export interface CanonicalMessage {
+    readonly role: Message["role"];
+    readonly blocks: readonly CanonicalMessageBlock[];
+    /** `blocks` remains authoritative; this only preserves an observable wire-shape distinction. */
+    readonly contentForm?: "text" | "blocks";
+    readonly toolCalls?: readonly ToolCall[];
+    readonly tokenCount?: number;
+    readonly providerReplay?: ProviderReplay;
+}
+export interface CanonicalRenderedContext {
+    readonly systemText: string;
+    readonly systemStable?: string;
+    readonly systemKnowledge?: string;
+    readonly turns: readonly CanonicalMessage[];
+    readonly stateTurn?: CanonicalMessage;
+    readonly frozenPrefixLen?: number;
+    readonly budgetOverflow?: RenderedContext["budgetOverflow"];
+}
+export interface CanonicalAdapterInput {
+    readonly context: CanonicalRenderedContext;
+    readonly tools: readonly ToolSchema[];
+    readonly resolved: ResolvedProviderRuntime<unknown>;
+    readonly extensions: Readonly<Record<string, unknown>>;
+}
+export declare function validateToolOutputBlocks(blocks: readonly ToolOutputBlock[]): void;
+export declare function projectToolOutputToText(blocks: readonly ToolOutputBlock[]): string;
+export declare function normalizeToolResultPart(part: ToolResultPart): CanonicalToolResult;
+/** Attach process-local blocks only within the operation that produced them. */
+export declare function attachToolOutputOverlay(context: RenderedContext, overlay: ReadonlyMap<string, readonly ToolOutputBlock[]>): RenderedContext;
+export declare function normalizeCanonicalContext(context: RenderedContext, replayForMessage?: (message: Message) => ProviderReplay | undefined): CanonicalRenderedContext;
+/** Full-tree validation uses the resolved operation capabilities. Unknown stays unknown/fail-open. */
+export declare function validateCanonicalAdapterInput(input: CanonicalAdapterInput): void;
+export declare function normalizeCanonicalAdapterInput(input: {
+    context: RenderedContext;
+    tools: readonly ToolSchema[];
+    resolved: ResolvedProviderRuntime<unknown>;
+    extensions?: Readonly<Record<string, unknown>>;
+    replayForMessage?: (message: Message) => ProviderReplay | undefined;
+}): CanonicalAdapterInput;
+export declare function normalizeToolResultContent(callId: string, output: string, isError: boolean, contentParts: readonly ToolOutputBlock[] | undefined): CanonicalToolResult;