@velum-labs/routekit-gateway 0.9.0

package/dist/index.js

@@ -0,0 +1,23 @@
+/** Product-neutral RouteKit gateway and router. */
+export { startGateway } from "./server.js";
+export { startSwitchingGatewayProxy } from "./switching-proxy.js";
+export { joinPath, ModelRoutedBackend, OpenAiBackend } from "./backend.js";
+export { AnthropicBackend, CodexResponsesBackend, GoogleGenAiBackend } from "./provider-backends.js";
+export { CatalogBackend, isSubscriptionProvider, NoModelAvailableError, normalizeRouterConfigAliases, parseRouterConfig, routerConfigSchema, splitNamespacedModel, UnknownModelError } from "./router.js";
+export { API_PROVIDER_IDS, ApiProviderSource, parseDiscoveredModels, parseReasoningCapabilities, PROVIDER_IDS, SUBSCRIPTION_PROVIDER_IDS } from "./provider-source.js";
+export { endpointHealthProbe, probeEndpointHealth, providerAuthHeaders } from "./endpoint-health.js";
+export { CapacityPool } from "./capacity-pool.js";
+export { effectiveModel, isStream, withDefaultModel } from "./adapters/chat.js";
+export { isCursorChatBody, translateCursorRequest } from "./adapters/cursor.js";
+export { anthropicModelsResponse, anthropicToChat, CLAUDE_ALIAS_PREFIX, chatToAnthropicMessage, claudeModelAlias, countTokensEstimate, handleAnthropicMessages, handleCountTokens, mapStopReason, openAiSseToAnthropic } from "./adapters/anthropic.js";
+export { chatToResponses, customToolNames, handleResponses, openAiSseToResponses, responsesToChat, responsesToolRegistry } from "./adapters/responses.js";
+export { MAX_WEB_SEARCHES_PER_TURN, resolveWebSearchExecutor } from "./adapters/web-search.js";
+export { DIALECT_DROPPED_ATTRIBUTE, droppedField, resetDroppedFieldWarnings, withDroppedFieldSpan } from "./adapters/dropped.js";
+export { ACP_PROTOCOL_VERSION, runAcpAgent } from "./acp-agent.js";
+export { ACP_REGISTRY_URL, fetchAcpRegistry, installAcpAdapters } from "./acp-registry.js";
+export { DEFAULT_MODEL_PRICING, estimateCost, formatUsd, lookupPricing, meterCall, parseUsage, parseUsageFromSse } from "./cost.js";
+export { buildModelCallRecord, MODEL_CALL_ID_HEADER, modelCallId, readProducerVersion, resolveProducerGitSha, responseBodyHash, UNKNOWN_GIT_SHA } from "./provenance.js";
+export { authorizedRequest } from "./auth.js";
+export { errorEvent, finishChunk, noticeChunk, reasoningChunk, sseResponse } from "./sse-wire.js";
+export { ChatStreamAssembler } from "./sse/chat-assembler.js";
+export { decodeBufferedSse, SseDecoder, SseParseError } from "./sse/parse.js";

package/dist/provenance.d.ts

@@ -0,0 +1,31 @@
+import type { ModelCallContract, RequestAttribution } from "@velum-labs/routekit-contracts";
+export type GatewayDialect = "openai-chat" | "openai-embeddings" | "anthropic-messages" | "openai-responses";
+export declare const MODEL_CALL_ID_HEADER = "x-routekit-model-call-id";
+export declare const UNKNOWN_GIT_SHA = "unknown";
+export declare function resolveProducerGitSha(fromDir?: string): string;
+export declare function readProducerVersion(fromDir?: string, fallback?: string): string;
+export type ModelGatewayCallContext = {
+    callId: string;
+    dialect: GatewayDialect;
+    requestedModel: string | undefined;
+    model: string | undefined;
+    stream: boolean;
+    requestBody: unknown;
+    startedAt: string;
+    endpointId?: string;
+    attribution?: RequestAttribution;
+};
+export type ModelGatewayCallResult = {
+    statusCode: number;
+    responseBody?: Buffer;
+    durationMs: number;
+    error?: unknown;
+};
+export type ModelCallRecord = ModelCallContract;
+export type ProvenanceSink = {
+    onModelCall?(record: ModelCallRecord): void;
+    onModelCallRaw?(context: ModelGatewayCallContext, result: ModelGatewayCallResult): void;
+};
+export declare function buildModelCallRecord(context: ModelGatewayCallContext, result: ModelGatewayCallResult): ModelCallRecord;
+export declare function modelCallId(): string;
+export declare function responseBodyHash(body: Buffer): string;

package/dist/provenance.js

@@ -0,0 +1,191 @@
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { artifactHash, requestHash, responseHash } from "@velum-labs/routekit-contracts";
+import { meterCall, parseUsage, parseUsageFromSse } from "./cost.js";
+export const MODEL_CALL_ID_HEADER = "x-routekit-model-call-id";
+export const UNKNOWN_GIT_SHA = "unknown";
+const GIT_SHA_PATTERN = /^[a-f0-9]{40}$/;
+function moduleDir() {
+    return dirname(fileURLToPath(import.meta.url));
+}
+export function resolveProducerGitSha(fromDir = moduleDir()) {
+    const stamped = process.env.ROUTEKIT_BUILD_GIT_SHA?.trim();
+    if (stamped !== undefined && GIT_SHA_PATTERN.test(stamped))
+        return stamped;
+    if (!fromDir.includes("node_modules")) {
+        const result = spawnSync("git", ["rev-parse", "HEAD"], { cwd: fromDir, encoding: "utf8" });
+        if (result.status === 0 && GIT_SHA_PATTERN.test(result.stdout.trim())) {
+            return result.stdout.trim();
+        }
+    }
+    return UNKNOWN_GIT_SHA;
+}
+export function readProducerVersion(fromDir = moduleDir(), fallback = "0.0.0") {
+    let dir = fromDir;
+    for (let depth = 0; depth < 8; depth += 1) {
+        try {
+            const parsed = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+            if (typeof parsed.version === "string" && parsed.version.length > 0)
+                return parsed.version;
+        }
+        catch {
+            // Continue toward the filesystem root.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return fallback;
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function parseJson(buffer) {
+    if (buffer === undefined || buffer.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(buffer.toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function responseText(buffer) {
+    return buffer?.toString("utf8") ?? "";
+}
+function requestMessages(body) {
+    const messages = asRecord(body)?.messages;
+    if (!Array.isArray(messages))
+        return [{ role: "user", content: requestHash(body) }];
+    const projected = messages.flatMap((message) => {
+        const item = asRecord(message);
+        const role = item?.role;
+        if (role !== "system" && role !== "user" && role !== "assistant" && role !== "tool")
+            return [];
+        return [{ role, content: requestHash(item?.content ?? "") }];
+    });
+    return projected.length > 0 ? projected : [{ role: "user", content: requestHash(body) }];
+}
+function usageFromResponse(body) {
+    const parsed = asRecord(parseJson(body));
+    const usage = parseUsage(parsed?.usage) ?? parseUsageFromSse(responseText(body));
+    if (usage === undefined)
+        return undefined;
+    return {
+        ...(usage.promptTokens !== undefined ? { prompt_tokens: usage.promptTokens } : {}),
+        ...(usage.completionTokens !== undefined ? { completion_tokens: usage.completionTokens } : {}),
+        ...(usage.totalTokens !== undefined ? { total_tokens: usage.totalTokens } : {})
+    };
+}
+function providerRequestId(body) {
+    const id = asRecord(parseJson(body))?.id;
+    return typeof id === "string" && id.length > 0 ? id : undefined;
+}
+function providerError(result) {
+    if (result.error === undefined && result.statusCode >= 200 && result.statusCode < 400) {
+        return undefined;
+    }
+    const responseError = asRecord(asRecord(parseJson(result.responseBody))?.error);
+    const noModelAvailable = result.statusCode === 503 &&
+        responseError?.type === "unavailable" &&
+        responseError.message === "no model is available; configure a provider";
+    const kind = noModelAvailable
+        ? "capability_missing"
+        : result.statusCode === 408
+            ? "timeout"
+            : result.statusCode === 429
+                ? "rate_limited"
+                : result.statusCode === 400 || result.statusCode === 422
+                    ? "validation_error"
+                    : "provider_error";
+    const message = kind === "capability_missing"
+        ? "no model route is configured"
+        : kind === "timeout"
+            ? "provider request timed out"
+            : kind === "rate_limited"
+                ? "provider rate limited the request"
+                : kind === "validation_error"
+                    ? "provider rejected the request"
+                    : "provider request failed";
+    return {
+        kind,
+        message,
+        retryable: !noModelAvailable &&
+            (result.statusCode === 408 || result.statusCode === 429 || result.statusCode >= 500)
+    };
+}
+export function buildModelCallRecord(context, result) {
+    const usage = usageFromResponse(result.responseBody);
+    const callCost = meterCall({
+        model: context.model ?? context.requestedModel ?? "unknown",
+        usage: usage === undefined
+            ? undefined
+            : {
+                promptTokens: usage.prompt_tokens,
+                completionTokens: usage.completion_tokens,
+                totalTokens: usage.total_tokens
+            }
+    });
+    const error = providerError(result);
+    const metadata = {
+        dialect: context.dialect,
+        stream: context.stream,
+        http_status: result.statusCode,
+        duration_ms: result.durationMs,
+        requested_model: context.requestedModel ?? null,
+        unknown_usage: callCost.unknownUsage,
+        unknown_cost: callCost.unknownCost,
+        ...(context.attribution !== undefined
+            ? {
+                attribution: {
+                    effective_model: context.attribution.effective_model,
+                    ...(context.attribution.native_model !== undefined
+                        ? { native_model: context.attribution.native_model }
+                        : {}),
+                    provider: context.attribution.provider,
+                    billing_mode: context.attribution.billing_mode,
+                    ...(context.attribution.account !== undefined
+                        ? { account: { seat: context.attribution.account.seat } }
+                        : {}),
+                    attempts: context.attribution.attempts,
+                    retries: context.attribution.retries,
+                    account_failovers: context.attribution.account_failovers
+                }
+            }
+            : {}),
+        ...(callCost.costUsd !== undefined ? { cost_estimate_usd: callCost.costUsd } : {})
+    };
+    return {
+        call_id: context.callId,
+        endpoint_id: context.endpointId ?? context.dialect,
+        ...(providerRequestId(result.responseBody) !== undefined
+            ? { provider_request_id: providerRequestId(result.responseBody) }
+            : {}),
+        model: context.model ?? context.requestedModel ?? "unknown",
+        request_hash: requestHash(context.requestBody),
+        ...(result.responseBody !== undefined
+            ? { response_hash: responseHash(responseText(result.responseBody)) }
+            : {}),
+        messages: requestMessages(context.requestBody),
+        status: error === undefined ? "succeeded" : "failed",
+        side_effects: "none",
+        started_at: context.startedAt,
+        finished_at: new Date(new Date(context.startedAt).getTime() + result.durationMs).toISOString(),
+        latency_ms: result.durationMs,
+        ...(usage !== undefined ? { usage } : {}),
+        ...(error !== undefined ? { error } : {}),
+        metadata
+    };
+}
+export function modelCallId() {
+    return `model_call_${randomUUID()}`;
+}
+export function responseBodyHash(body) {
+    return artifactHash(body);
+}

package/dist/provider-backends.d.ts

@@ -0,0 +1,40 @@
+import type { Backend, BackendRequestOptions } from "./backend.js";
+export type ProviderBackendOptions = {
+    baseUrl: string;
+    apiKey: string;
+    defaultModel?: string;
+    headers?: Record<string, string>;
+    transport?: ProviderTransport;
+    forceStream?: boolean;
+    omitSampling?: boolean;
+};
+export type ProviderTransport = (url: string, init: RequestInit, options?: BackendRequestOptions) => Promise<Response>;
+declare abstract class HttpProviderBackend implements Backend {
+    readonly defaultModel: string | undefined;
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly extraHeaders: Record<string, string>;
+    readonly transport: ProviderTransport;
+    constructor(options: ProviderBackendOptions);
+    listModelIds(): readonly string[];
+    servesModel(model: string): boolean;
+    models(): Promise<Response>;
+    embeddings(): Promise<Response>;
+    abstract chat(body: unknown, signal?: AbortSignal, options?: BackendRequestOptions): Promise<Response>;
+}
+export declare class AnthropicBackend extends HttpProviderBackend {
+    #private;
+    chat(body: unknown, signal?: AbortSignal, options?: BackendRequestOptions): Promise<Response>;
+}
+export declare class GoogleGenAiBackend extends HttpProviderBackend {
+    #private;
+    chat(body: unknown, signal?: AbortSignal, options?: BackendRequestOptions): Promise<Response>;
+}
+export declare class CodexResponsesBackend extends HttpProviderBackend {
+    #private;
+    constructor(options: ProviderBackendOptions & {
+        accountId?: string;
+    });
+    chat(body: unknown, signal?: AbortSignal, options?: BackendRequestOptions): Promise<Response>;
+}
+export {};