@deepstrike/sdk 0.2.52 → 0.2.61

package/dist/providers/content-normalization.js

@@ -0,0 +1,238 @@
+import { requireContentDisposition } from "./content-policy.js";
+export class ContentValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ContentValidationError";
+    }
+}
+export class ToolResultProjectionConflictError extends ContentValidationError {
+    constructor(callId) {
+        super(`Tool result projection conflict for ${callId}: output does not match contentParts`);
+        this.name = "ToolResultProjectionConflictError";
+    }
+}
+function requireNonEmpty(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new ContentValidationError(`${label} must be a non-empty string`);
+    }
+}
+function requireBase64(value, label) {
+    requireNonEmpty(value, label);
+    if (value.length % 4 !== 0
+        || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+        throw new ContentValidationError(`${label} is not valid base64`);
+    }
+}
+function validateSource(source, modality) {
+    if (!source || typeof source !== "object") {
+        throw new ContentValidationError(`${modality} source is required`);
+    }
+    switch (source.kind) {
+        case "url":
+            requireNonEmpty(source.url, `${modality} URL`);
+            return;
+        case "base64":
+            requireBase64(source.data, `${modality} base64 data`);
+            return;
+        case "fileId":
+            requireNonEmpty(source.id, `${modality} file id`);
+            return;
+        case "object":
+            requireNonEmpty(source.handle, `${modality} object handle`);
+            return;
+        default: throw new ContentValidationError(`${modality} source kind is invalid`);
+    }
+}
+export function validateToolOutputBlocks(blocks) {
+    for (const raw of blocks) {
+        if (!raw || typeof raw !== "object")
+            throw new ContentValidationError("tool output block must be an object");
+        const block = raw;
+        switch (block.type) {
+            case "text":
+                if (typeof block.text !== "string")
+                    throw new ContentValidationError("tool output text must be a string");
+                break;
+            case "image":
+            case "audio":
+            case "video":
+            case "file":
+                validateSource(block.source, String(block.type));
+                break;
+            case "tool_result":
+                throw new ContentValidationError("nested tool_result blocks are forbidden");
+            default:
+                throw new ContentValidationError(`unknown tool output block type: ${String(block.type)}`);
+        }
+    }
+}
+export function projectToolOutputToText(blocks) {
+    validateToolOutputBlocks(blocks);
+    return blocks.map(block => block.type === "text" ? block.text : `[${block.type}]`).join("\n");
+}
+export function normalizeToolResultPart(part) {
+    if (part.contentParts === undefined) {
+        return {
+            type: "tool_result",
+            callId: part.callId,
+            blocks: [{ type: "text", text: part.output }],
+            isError: part.isError,
+            contentForm: "text",
+        };
+    }
+    const projection = projectToolOutputToText(part.contentParts);
+    if (projection !== part.output)
+        throw new ToolResultProjectionConflictError(part.callId);
+    return {
+        type: "tool_result",
+        callId: part.callId,
+        blocks: part.contentParts,
+        isError: part.isError,
+        contentForm: "blocks",
+    };
+}
+function attachMessage(message, overlay) {
+    const needs = message.contentParts?.some(part => part.type === "tool_result" && part.contentParts === undefined && overlay.has(part.callId));
+    if (!needs)
+        return message;
+    return {
+        ...message,
+        contentParts: message.contentParts.map(part => part.type === "tool_result" && part.contentParts === undefined && overlay.has(part.callId)
+            ? { ...part, contentParts: [...overlay.get(part.callId)] }
+            : part),
+    };
+}
+/** Attach process-local blocks only within the operation that produced them. */
+export function attachToolOutputOverlay(context, overlay) {
+    if (overlay.size === 0)
+        return context;
+    const turns = context.turns.map(message => attachMessage(message, overlay));
+    const stateTurn = context.stateTurn ? attachMessage(context.stateTurn, overlay) : undefined;
+    if (turns.every((turn, index) => turn === context.turns[index]) && stateTurn === context.stateTurn)
+        return context;
+    return { ...context, turns, ...(stateTurn ? { stateTurn } : {}) };
+}
+function assertSupported(modality, capabilities, providerId) {
+    if (capabilities.inputModalities[modality].state === "unsupported") {
+        throw new ContentValidationError(`UnsupportedModality: ${modality} is not supported by ${providerId}`);
+    }
+}
+function validateSourceAffinity(modality, source, capabilities, resolved) {
+    const key = modality === "image"
+        ? source.kind === "url" ? "imageUrl" : source.kind === "base64" ? "imageBase64" : source.kind === "fileId" ? "fileId" : undefined
+        : modality === "audio"
+            ? source.kind === "url" ? "audioUrl" : source.kind === "base64" ? "audioBase64" : source.kind === "fileId" ? "fileId" : undefined
+            : source.kind === "fileId" ? "fileId" : undefined;
+    if (key && capabilities.mediaForms[key].state === "unsupported") {
+        throw new ContentValidationError(`Unsupported media source ${source.kind} for ${modality} on ${resolved.identity.providerId}`);
+    }
+    validateFileAffinity(source, resolved);
+}
+function validateFileAffinity(source, resolved) {
+    if (source.kind === "fileId" && source.affinity) {
+        if (source.affinity.providerId !== resolved.identity.providerId
+            || source.affinity.endpointId !== resolved.identity.endpointId) {
+            throw new ContentValidationError(`Provider file ${source.id} belongs to ${source.affinity.providerId}/${source.affinity.endpointId}, `
+                + `not ${resolved.identity.providerId}/${resolved.identity.endpointId}`);
+        }
+    }
+}
+function normalizeMessage(message, replayForMessage) {
+    const providerReplay = replayForMessage?.(message);
+    const blocks = message.contentParts === undefined
+        ? [{ type: "text", text: message.content }]
+        : message.contentParts.map(part => {
+            if (part.type === "text")
+                return { type: "text", text: part.text };
+            if (part.type === "image") {
+                if ((part.url === undefined) === (part.data === undefined)) {
+                    throw new ContentValidationError("image requires exactly one of url or data");
+                }
+                return {
+                    type: "image",
+                    source: part.data !== undefined
+                        ? { kind: "base64", data: part.data }
+                        : { kind: "url", url: part.url },
+                    ...(part.mediaType ? { mediaType: part.mediaType } : {}),
+                    ...(part.detail ? { providerOptions: { openai_detail: part.detail } } : {}),
+                };
+            }
+            if (part.type === "audio") {
+                return {
+                    type: "audio",
+                    source: { kind: "base64", data: part.data },
+                    mediaType: part.mediaType,
+                };
+            }
+            return normalizeToolResultPart(part);
+        });
+    return {
+        role: message.role,
+        blocks,
+        contentForm: message.contentParts === undefined ? "text" : "blocks",
+        ...(message.toolCalls ? { toolCalls: message.toolCalls } : {}),
+        ...(message.tokenCount !== undefined ? { tokenCount: message.tokenCount } : {}),
+        ...(providerReplay ? { providerReplay } : {}),
+    };
+}
+export function normalizeCanonicalContext(context, replayForMessage) {
+    return {
+        systemText: context.systemText,
+        ...(context.systemStable !== undefined ? { systemStable: context.systemStable } : {}),
+        ...(context.systemKnowledge !== undefined ? { systemKnowledge: context.systemKnowledge } : {}),
+        turns: context.turns.map(message => normalizeMessage(message, replayForMessage)),
+        ...(context.stateTurn ? { stateTurn: normalizeMessage(context.stateTurn, replayForMessage) } : {}),
+        ...(context.frozenPrefixLen !== undefined ? { frozenPrefixLen: context.frozenPrefixLen } : {}),
+        ...(context.budgetOverflow !== undefined ? { budgetOverflow: context.budgetOverflow } : {}),
+    };
+}
+function validateCanonicalMessage(message, resolved) {
+    for (const item of message.blocks) {
+        const placement = item.type === "tool_result" ? "tool_result" : "message";
+        const blocks = item.type === "tool_result" ? item.blocks : [item];
+        validateToolOutputBlocks(blocks);
+        for (const block of blocks) {
+            if (block.type === "text")
+                continue;
+            // Protocol policy is the stable user-visible reason for document/video refusal; a model
+            // capability cannot make a protocol-level unsupported shape serializable.
+            const disposition = requireContentDisposition(resolved.identity.protocol, block.type, placement);
+            // Current bridge implementations exist only for document/video tool output: their
+            // serializers send the deterministic visible text projection instead of the source.
+            // Audio and message content retain their source-form checks because their wires have
+            // different native constraints and no generic text bridge carrier.
+            if (disposition === "bridge" && placement === "tool_result" && (block.type === "file" || block.type === "video")) {
+                validateFileAffinity(block.source, resolved);
+                continue;
+            }
+            assertSupported(block.type, resolved.effectiveCapabilities, resolved.identity.providerId);
+            validateSourceAffinity(block.type, block.source, resolved.effectiveCapabilities, resolved);
+        }
+    }
+}
+/** Full-tree validation uses the resolved operation capabilities. Unknown stays unknown/fail-open. */
+export function validateCanonicalAdapterInput(input) {
+    for (const message of input.context.turns)
+        validateCanonicalMessage(message, input.resolved);
+    if (input.context.stateTurn)
+        validateCanonicalMessage(input.context.stateTurn, input.resolved);
+}
+export function normalizeCanonicalAdapterInput(input) {
+    const canonical = {
+        context: normalizeCanonicalContext(input.context, input.replayForMessage),
+        tools: input.tools,
+        resolved: input.resolved,
+        extensions: input.extensions ?? {},
+    };
+    validateCanonicalAdapterInput(canonical);
+    return canonical;
+}
+export function normalizeToolResultContent(callId, output, isError, contentParts) {
+    return normalizeToolResultPart({
+        type: "tool_result",
+        callId,
+        output,
+        isError,
+        ...(contentParts === undefined ? {} : { contentParts: [...contentParts] }),
+    });
+}

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

@@ -0,0 +1,16 @@
+import type { InputModality } from "./protocol-capabilities.js";
+export type ContentPlacement = "message" | "tool_result";
+export type ContentDisposition = "native" | "bridge" | "unsupported";
+/**
+ * Provider serialization policy for canonical content. `bridge` means the protocol has no
+ * structured equivalent for that placement, but serializers may send the visible text projection.
+ * It never permits dropping a block or replacing it with an empty string.
+ */
+export declare function contentDispositionFor(protocol: string, modality: InputModality, placement: ContentPlacement): ContentDisposition;
+export declare class ContentPolicyError extends Error {
+    readonly protocol: string;
+    readonly modality: InputModality;
+    readonly placement: ContentPlacement;
+    constructor(protocol: string, modality: InputModality, placement: ContentPlacement);
+}
+export declare function requireContentDisposition(protocol: string, modality: InputModality, placement: ContentPlacement): ContentDisposition;

package/dist/providers/content-policy.js

@@ -0,0 +1,39 @@
+/**
+ * Provider serialization policy for canonical content. `bridge` means the protocol has no
+ * structured equivalent for that placement, but serializers may send the visible text projection.
+ * It never permits dropping a block or replacing it with an empty string.
+ */
+export function contentDispositionFor(protocol, modality, placement) {
+    if (modality === "text" || modality === "image") {
+        if (protocol === "ollama-chat" && modality === "image" && placement === "tool_result")
+            return "bridge";
+        return "native";
+    }
+    if (protocol === "openai-responses" && modality === "file" && placement === "message")
+        return "native";
+    if (protocol === "openai-responses" && modality === "file" && placement === "tool_result")
+        return "bridge";
+    if (protocol === "openai-chat" && ["audio", "file", "video"].includes(modality))
+        return "bridge";
+    if (protocol === "gemini" && ["audio", "file", "video"].includes(modality))
+        return "bridge";
+    return "unsupported";
+}
+export class ContentPolicyError extends Error {
+    protocol;
+    modality;
+    placement;
+    constructor(protocol, modality, placement) {
+        super(`Unsupported content policy: ${modality} ${placement} is not supported by ${protocol}`);
+        this.protocol = protocol;
+        this.modality = modality;
+        this.placement = placement;
+        this.name = "ContentPolicyError";
+    }
+}
+export function requireContentDisposition(protocol, modality, placement) {
+    const disposition = contentDispositionFor(protocol, modality, placement);
+    if (disposition === "unsupported")
+        throw new ContentPolicyError(protocol, modality, placement);
+    return disposition;
+}

package/dist/providers/credentials.d.ts

@@ -0,0 +1,83 @@
+import type { EndpointProfileId, EndpointProtocol, ProviderId } from "./endpoints.js";
+export type ProviderCredential = {
+    type: "api_key";
+    value: string;
+} | {
+    type: "bearer";
+    value: string;
+};
+export interface CredentialRequest {
+    providerId: ProviderId;
+    modelId: string;
+    endpointId: EndpointProfileId;
+    protocol: EndpointProtocol;
+}
+export type CredentialResolver = (request: CredentialRequest) => ProviderCredential | undefined | Promise<ProviderCredential | undefined>;
+export interface OAuthAccessToken {
+    accessToken: string;
+    /** Epoch time on the clock supplied to the resolver. The token is invalid at this instant. */
+    expiresAt: number;
+    scopes?: readonly string[];
+    audience?: string;
+}
+export interface OAuthRefreshRequest {
+    providerId: ProviderId;
+    audience?: string;
+    requiredScopes: readonly string[];
+}
+export interface OAuthCredentialResolverOptions {
+    providerId: ProviderId;
+    /** Provider-owned refresh/ADC bridge. The Host owns its transport and refresh token. */
+    refresh: (request: OAuthRefreshRequest) => OAuthAccessToken | Promise<OAuthAccessToken>;
+    requiredScopes?: readonly string[];
+    audience?: string;
+    clock?: () => number;
+}
+export interface CredentialOptions {
+    apiKey?: string;
+    bearerToken?: string;
+    credentialResolver?: CredentialResolver;
+}
+/** A deliberately non-sensitive credential failure. Never add resolver output to this error. */
+export declare class CredentialResolutionError extends Error {
+    readonly code: "credential_unavailable" | "credential_invalid" | "credential_resolver_failed" | "credential_refresh_failed" | "credential_oauth_scope_mismatch" | "credential_oauth_audience_mismatch" | "credential_revoked" | "credential_auth_mode_unsupported";
+    readonly providerId: ProviderId;
+    readonly retryable: boolean;
+    constructor(code: CredentialResolutionError["code"], providerId: ProviderId, retryable?: boolean);
+}
+/**
+ * Host-owned OAuth/ADC extension. It retains only a refreshable bearer in process memory,
+ * never exposes refresh-token material, and coalesces concurrent refreshes for one provider.
+ */
+export declare class OAuthCredentialResolver {
+    private readonly providerId;
+    private readonly refresh;
+    private readonly requiredScopes;
+    private readonly audience?;
+    private readonly clock;
+    private token?;
+    private refreshInFlight?;
+    private revoked;
+    constructor(options: OAuthCredentialResolverOptions);
+    /** An arrow field intentionally remains bound when passed as `credentialResolver`. */
+    readonly resolve: CredentialResolver;
+    revoke(): void;
+    status(): {
+        providerId: ProviderId;
+        revoked: boolean;
+        hasUsableToken: boolean;
+    };
+    private usable;
+    private refreshToken;
+    private assertUsable;
+}
+/** Safe for diagnostics and event metadata. It intentionally has no credential value. */
+export declare function redactCredential(credential: ProviderCredential): {
+    type: ProviderCredential["type"];
+};
+export declare function resolveCredential(request: CredentialRequest, options: CredentialOptions): Promise<ProviderCredential>;
+/**
+ * The synchronous factory remains synchronous. A resolver which performs I/O must use
+ * `resolveProviderRuntimeAsync` / `createProviderAsync` instead of risking an implicit request.
+ */
+export declare function resolveCredentialSync(request: CredentialRequest, options: CredentialOptions): ProviderCredential;

package/dist/providers/credentials.js

@@ -0,0 +1,190 @@
+/** A deliberately non-sensitive credential failure. Never add resolver output to this error. */
+export class CredentialResolutionError extends Error {
+    code;
+    providerId;
+    retryable;
+    constructor(code, providerId, retryable = false) {
+        super(messageForCredentialError(code, providerId));
+        this.name = "CredentialResolutionError";
+        this.code = code;
+        this.providerId = providerId;
+        this.retryable = retryable;
+    }
+}
+/**
+ * Host-owned OAuth/ADC extension. It retains only a refreshable bearer in process memory,
+ * never exposes refresh-token material, and coalesces concurrent refreshes for one provider.
+ */
+export class OAuthCredentialResolver {
+    providerId;
+    refresh;
+    requiredScopes;
+    audience;
+    clock;
+    token;
+    refreshInFlight;
+    revoked = false;
+    constructor(options) {
+        this.providerId = options.providerId;
+        this.refresh = options.refresh;
+        this.requiredScopes = [...(options.requiredScopes ?? [])];
+        this.audience = options.audience;
+        this.clock = options.clock ?? Date.now;
+    }
+    /** An arrow field intentionally remains bound when passed as `credentialResolver`. */
+    resolve = async (request) => {
+        if (request.providerId !== this.providerId)
+            throw unavailable(request.providerId);
+        if (this.revoked)
+            throw new CredentialResolutionError("credential_revoked", this.providerId);
+        const token = this.usable(this.token) ? this.token : await this.refreshToken();
+        this.assertUsable(token);
+        if (this.revoked)
+            throw new CredentialResolutionError("credential_revoked", this.providerId);
+        return { type: "bearer", value: token.accessToken };
+    };
+    revoke() {
+        this.revoked = true;
+        this.token = undefined;
+    }
+    status() {
+        return {
+            providerId: this.providerId,
+            revoked: this.revoked,
+            hasUsableToken: !this.revoked && this.usable(this.token),
+        };
+    }
+    usable(token) {
+        return token !== undefined && Number.isFinite(token.expiresAt) && token.expiresAt > this.clock();
+    }
+    async refreshToken() {
+        if (!this.refreshInFlight) {
+            this.refreshInFlight = Promise.resolve()
+                .then(() => this.refresh({
+                providerId: this.providerId,
+                ...(this.audience === undefined ? {} : { audience: this.audience }),
+                requiredScopes: this.requiredScopes,
+            }))
+                .then(token => {
+                this.assertUsable(token);
+                if (this.revoked)
+                    throw new CredentialResolutionError("credential_revoked", this.providerId);
+                this.token = token;
+                return token;
+            })
+                .catch(error => {
+                if (error instanceof CredentialResolutionError)
+                    throw error;
+                throw new CredentialResolutionError("credential_refresh_failed", this.providerId, true);
+            })
+                .finally(() => { this.refreshInFlight = undefined; });
+        }
+        return this.refreshInFlight;
+    }
+    assertUsable(token) {
+        if (!token
+            || typeof token.accessToken !== "string"
+            || token.accessToken.trim() === ""
+            || !Number.isFinite(token.expiresAt)
+            || token.expiresAt <= this.clock()) {
+            throw new CredentialResolutionError("credential_invalid", this.providerId);
+        }
+        if (this.audience !== undefined && token.audience !== this.audience) {
+            throw new CredentialResolutionError("credential_oauth_audience_mismatch", this.providerId);
+        }
+        const tokenScopes = new Set(token.scopes ?? []);
+        if (this.requiredScopes.some(scope => !tokenScopes.has(scope))) {
+            throw new CredentialResolutionError("credential_oauth_scope_mismatch", this.providerId);
+        }
+    }
+}
+/** Safe for diagnostics and event metadata. It intentionally has no credential value. */
+export function redactCredential(credential) {
+    return { type: credential.type };
+}
+export async function resolveCredential(request, options) {
+    const configured = configuredCredential(request.providerId, options);
+    if (configured)
+        return configured;
+    if (!options.credentialResolver)
+        throw unavailable(request.providerId);
+    let resolved;
+    try {
+        resolved = await options.credentialResolver(request);
+    }
+    catch (error) {
+        if (error instanceof CredentialResolutionError)
+            throw error;
+        throw new CredentialResolutionError("credential_resolver_failed", request.providerId);
+    }
+    return validateCredential(resolved, request.providerId);
+}
+/**
+ * The synchronous factory remains synchronous. A resolver which performs I/O must use
+ * `resolveProviderRuntimeAsync` / `createProviderAsync` instead of risking an implicit request.
+ */
+export function resolveCredentialSync(request, options) {
+    const configured = configuredCredential(request.providerId, options);
+    if (configured)
+        return configured;
+    if (!options.credentialResolver)
+        throw unavailable(request.providerId);
+    let resolved;
+    try {
+        resolved = options.credentialResolver(request);
+    }
+    catch (error) {
+        if (error instanceof CredentialResolutionError)
+            throw error;
+        throw new CredentialResolutionError("credential_resolver_failed", request.providerId);
+    }
+    if (isPromise(resolved)) {
+        throw new CredentialResolutionError("credential_resolver_failed", request.providerId);
+    }
+    return validateCredential(resolved, request.providerId);
+}
+function configuredCredential(providerId, options) {
+    const sources = [
+        options.apiKey === undefined ? undefined : { type: "api_key", value: options.apiKey },
+        options.bearerToken === undefined ? undefined : { type: "bearer", value: options.bearerToken },
+    ].filter((value) => value !== undefined);
+    if (sources.length > 1)
+        throw new CredentialResolutionError("credential_invalid", providerId);
+    return sources.length === 1 ? validateCredential(sources[0], providerId) : undefined;
+}
+function validateCredential(credential, providerId) {
+    if (!credential)
+        throw unavailable(providerId);
+    if ((credential.type !== "api_key" && credential.type !== "bearer")
+        || typeof credential.value !== "string"
+        || credential.value.trim() === "") {
+        throw new CredentialResolutionError("credential_invalid", providerId);
+    }
+    return credential;
+}
+function unavailable(providerId) {
+    return new CredentialResolutionError("credential_unavailable", providerId);
+}
+function messageForCredentialError(code, providerId) {
+    switch (code) {
+        case "credential_unavailable":
+            return `Missing credential for provider ${providerId}`;
+        case "credential_invalid":
+            return `Invalid credential for provider ${providerId}`;
+        case "credential_refresh_failed":
+            return `Credential refresh failed for provider ${providerId}`;
+        case "credential_oauth_scope_mismatch":
+            return `Credential scope does not satisfy provider ${providerId}`;
+        case "credential_oauth_audience_mismatch":
+            return `Credential audience does not match provider ${providerId}`;
+        case "credential_revoked":
+            return `Credential was revoked for provider ${providerId}`;
+        case "credential_auth_mode_unsupported":
+            return `Credential authentication mode is unsupported for provider ${providerId}`;
+        case "credential_resolver_failed":
+            return `Credential resolution failed for provider ${providerId}`;
+    }
+}
+function isPromise(value) {
+    return Boolean(value) && typeof value.then === "function";
+}