@velum-labs/routekit-gateway 0.18.6 → 1.0.0

package/README.md

@@ -4,10 +4,11 @@ Product-neutral model routing and provider egress for RouteKit.
 
 The package owns the `Backend` interface, HTTP gateway, OpenAI Chat,
 Responses, Anthropic Messages and Cursor adapters, SSE handling, ACP support,
-normalized call provenance, runtime-validated router configuration, model
-catalogs, provider sources, and provider-native egress.
+normalized call provenance, model catalogs, provider sources, and
+provider-native egress. Canonical router configuration belongs to
+`@velum-labs/routekit-config-core`.
 
-At startup `CatalogBackend` authenticates every explicitly configured provider,
+At startup `RoutingBackend` authenticates every explicitly configured provider,
 performs live model discovery, and publishes source-qualified
 `provider/model` IDs. Dispatch removes the source prefix before provider-native
 egress. An unavailable provider fails startup rather than silently shrinking
@@ -15,10 +16,10 @@ the catalog.
 
 ```ts
 import {
-  CatalogBackend,
-  parseRouterConfig,
+  RoutingBackend,
   startGateway
 } from "@velum-labs/routekit-gateway";
+import { parseRouterConfig } from "@velum-labs/routekit-config-core";
 ```
 
 API-key providers use registry-defined credentials and URLs. Multi-account

package/dist/{acp-registry.d.ts → acp/registry.d.ts}

@@ -1,11 +1,13 @@
 /**
  * ACP Registry integration. Resolves curated ACP-compatible agents (for
  * example the registry-backed `Codex CLI` and `Claude Agent` adapters) from the
- * ACP Registry so they can drive the generic ACP front door. The fetcher and
- * install directory are injectable for deterministic testing.
+ * ACP Registry so they can drive the generic ACP front door. The install
+ * directory is injectable for deterministic testing.
  *
  * Registry source: https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json
  */
+import { Effect } from "effect";
+import { HttpClient } from "effect/unstable/http";
 export declare const ACP_REGISTRY_URL = "https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json";
 export type AcpRegistryAgent = {
     id: string;
@@ -17,7 +19,6 @@ export type AcpRegistryAgent = {
 export type AcpRegistry = {
     agents: AcpRegistryAgent[];
 };
-export type AcpRegistryFetcher = (url: string) => Promise<unknown>;
 export type InstalledAcpAdapter = {
     id: string;
     name: string;
@@ -26,11 +27,10 @@ export type InstalledAcpAdapter = {
     installedAt: string;
     metadataPath: string;
 };
-export declare function fetchAcpRegistry(fetcher?: AcpRegistryFetcher, url?: string): Promise<AcpRegistry>;
+export declare function fetchAcpRegistry(url?: string): Effect.Effect<AcpRegistry, Error, HttpClient.HttpClient>;
 export type InstallAcpAdaptersOptions = {
     agentIds: string[];
     installDir: string;
-    fetcher?: AcpRegistryFetcher;
     url?: string;
 };
-export declare function installAcpAdapters(options: InstallAcpAdaptersOptions): Promise<InstalledAcpAdapter[]>;
+export declare function installAcpAdapters(options: InstallAcpAdaptersOptions): Effect.Effect<InstalledAcpAdapter[], Error, HttpClient.HttpClient>;

package/dist/acp/registry.js

@@ -0,0 +1,99 @@
+/**
+ * ACP Registry integration. Resolves curated ACP-compatible agents (for
+ * example the registry-backed `Codex CLI` and `Claude Agent` adapters) from the
+ * ACP Registry so they can drive the generic ACP front door. The install
+ * directory is injectable for deterministic testing.
+ *
+ * Registry source: https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { executeWebRequest, RouteKitFailure, routeKitError, toRouteKitFailure } from "@velum-labs/routekit-runtime/effect";
+import { Effect } from "effect";
+import { gatewayTry } from "../effect/gateway.js";
+export const ACP_REGISTRY_URL = "https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json";
+function normalizeRegistry(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new Error("ACP registry payload must be an object");
+    }
+    const agentsValue = raw.agents;
+    if (!Array.isArray(agentsValue)) {
+        throw new Error("ACP registry payload is missing an agents array");
+    }
+    const agents = [];
+    for (const entry of agentsValue) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const id = entry.id;
+        if (typeof id !== "string" || id.length === 0)
+            continue;
+        const agent = { id };
+        const name = entry.name;
+        if (typeof name === "string")
+            agent.name = name;
+        const version = entry.version;
+        if (typeof version === "string")
+            agent.version = version;
+        const description = entry.description;
+        if (typeof description === "string")
+            agent.description = description;
+        const distribution = entry.distribution;
+        if (typeof distribution === "object" && distribution !== null) {
+            agent.distribution = distribution;
+        }
+        agents.push(agent);
+    }
+    return { agents };
+}
+export function fetchAcpRegistry(url = ACP_REGISTRY_URL) {
+    return Effect.gen(function* () {
+        const response = yield* executeWebRequest(url).pipe(Effect.mapError((error) => routeKitError(error)));
+        if (!response.ok) {
+            return yield* new RouteKitFailure({
+                message: `ACP registry fetch failed: ${response.status}`
+            });
+        }
+        const payload = yield* Effect.tryPromise({
+            try: () => response.json(),
+            catch: (cause) => toRouteKitFailure(cause)
+        });
+        return normalizeRegistry(payload);
+    });
+}
+export function installAcpAdapters(options) {
+    return Effect.gen(function* () {
+        if (options.agentIds.length === 0) {
+            return yield* new RouteKitFailure({ message: "at least one ACP agent id is required" });
+        }
+        const registry = yield* fetchAcpRegistry(options.url ?? ACP_REGISTRY_URL);
+        const byId = new Map(registry.agents.map((agent) => [agent.id, agent]));
+        const dir = resolve(options.installDir);
+        yield* gatewayTry(() => mkdirSync(dir, { recursive: true }));
+        const installed = [];
+        for (const agentId of options.agentIds) {
+            const agent = byId.get(agentId);
+            if (agent === undefined) {
+                return yield* new RouteKitFailure({
+                    message: `ACP registry has no agent with id "${agentId}"`
+                });
+            }
+            if (agent.distribution === undefined) {
+                return yield* new RouteKitFailure({
+                    message: `ACP agent "${agentId}" has no distribution metadata`
+                });
+            }
+            const metadataPath = join(dir, `${agentId}.json`);
+            const record = {
+                id: agent.id,
+                name: agent.name ?? agent.id,
+                version: agent.version ?? "unknown",
+                distribution: agent.distribution,
+                installedAt: new Date().toISOString(),
+                metadataPath
+            };
+            yield* gatewayTry(() => writeFileSync(metadataPath, JSON.stringify(record, null, 2) + "\n"));
+            installed.push(record);
+        }
+        return installed;
+    });
+}

package/dist/adapters/anthropic-codec.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Anthropic Messages codec. Pure request/response translation between the
+ * Anthropic Messages wire and the gateway's OpenAI Chat Completions core.
+ * Streaming translation lives in `anthropic-stream.ts`; HTTP handling lives
+ * in `anthropic.ts`.
+ */
+import type { OpenAiChatResponse } from "../providers/protocol.js";
+import type { AnthropicRequest } from "./anthropic-wire.js";
+import type { ExecutedSearch, ServerToolLoopEvent } from "./server-tool-loop.js";
+export type { AnthropicRequest } from "./anthropic-wire.js";
+/**
+ * Whether an Anthropic tool is *server-executed* (run by Anthropic's backend,
+ * e.g. `web_search_20250305` / `code_execution_*`). Nothing behind this gateway
+ * can execute those, so advertising them to the upstream model would only produce
+ * calls nobody answers. Everything else — plain client tools (no `type` /
+ * `custom`) and Anthropic-defined client tools (`bash_*`, `text_editor_*`,
+ * `computer_*`), all of which the caller executes via ordinary `tool_use`
+ * blocks — is projected through.
+ */
+export declare function isAnthropicServerTool(tool: {
+    type?: string;
+}): boolean;
+/** A server web search tool declaration (`web_search_20250305` et al.) — the
+ *  one server tool the gateway can honor via its own web-search executor. */
+export declare function isAnthropicWebSearchTool(tool: {
+    type?: string;
+}): boolean;
+/** The name the gateway-executed web search tool is projected under chat-side. */
+export declare const WEB_SEARCH_TOOL_NAME = "web_search";
+/** Options gating server-executed tool projection (on iff an executor exists). */
+export type AnthropicTranslationOptions = {
+    serverTools?: boolean;
+};
+type OpenAiResponse = OpenAiChatResponse;
+export declare function thinkingValidationError(body: AnthropicRequest): string | undefined;
+/**
+ * Translate an Anthropic Messages request to an OpenAI Chat Completions body.
+ * The upstream model is always the backend's own model (Claude Code sends a
+ * `claude-*` id the local server would not recognise); the requested id is
+ * only echoed back in the response.
+ */
+export declare function anthropicToChat(body: AnthropicRequest, backendModel: string | undefined, options?: AnthropicTranslationOptions): Record<string, unknown>;
+export declare function mapStopReason(finishReason: string | null | undefined): string;
+export declare function chatToAnthropicMessage(openai: OpenAiResponse, model: string, searches?: readonly ExecutedSearch[], events?: readonly ServerToolLoopEvent[]): Record<string, unknown>;
+export declare function countTokensEstimate(body: AnthropicRequest): number;