@agentproto/llm-endpoint 0.8.0

package/dist/index.d.ts

@@ -0,0 +1,427 @@
+import * as node_http from 'node:http';
+import { IncomingMessage, ServerResponse } from 'http';
+
+/**
+ * Capability tier of a route, coarse enough to map onto the four Claude
+ * families. Used by {@link toAnthropicStyle} to pick a family prefix for the
+ * generated Anthropic-shaped id (see {@link TIER_TO_FAMILY}).
+ */
+type ModelTier = 'extra-high' | 'high' | 'medium' | 'small';
+interface ModelRoute {
+    provider: string;
+    model: string;
+    /**
+     * Optional Claude-shaped compatibility alias. Committed packs never hardcode
+     * this — it is populated either by a local pack (loaded from
+     * `packs.local.json`) or on demand by {@link toAnthropicStyle} when a request
+     * opts into the Anthropic-style format. Committed packs use
+     * provider-transparent model IDs and never pretend to be real Claude models.
+     */
+    equivalentClaudeName?: string;
+    /**
+     * Coarse capability tier. Only consumed by {@link toAnthropicStyle} to select
+     * a Claude family for the generated alias; ignored on every routing path.
+     */
+    tier?: ModelTier;
+    /**
+     * Verified context window of the upstream route, in tokens. Surfaced in the
+     * /v1/models metadata when present; never guessed — leave absent when the
+     * limit for this specific route is not verified.
+     */
+    contextWindow?: number;
+    /**
+     * Verified max output tokens for the upstream route, in tokens. Same
+     * honesty rule as {@link ModelRoute.contextWindow}.
+     */
+    maxOutputTokens?: number;
+}
+/**
+ * A pack is a curated set of model routes. Packs solve the collision problem
+ * when multiple providers share the same display name, and they let users opt
+ * into local compatibility aliases for clients that only speak the Anthropic
+ * model namespace.
+ *
+ * Selection methods:
+ *   - URL path: /v1/{packId}/messages → pack = {packId}
+ *   - Query param: /v1/messages?pack={packId}
+ *   - Header: X-Proxy-Pack: {packId}
+ *   - Default: no pack specified → uses 'default' pack
+ */
+interface ModelPack {
+    id: string;
+    label: string;
+    description: string;
+    models: Record<string, ModelRoute>;
+    /**
+     * Exclude-list of tool-name patterns applied to every request routed through
+     * this pack (wildcards allowed, e.g. "mcp__*"). Cuts upstream prefill cost
+     * when a client (e.g. Claude Desktop) sends hundreds of tool definitions.
+     * Applied after per-request header/query trims so an explicit client
+     * X-Proxy-Tools allow-list still wins.
+     */
+    toolsExclude?: string[];
+    /**
+     * Allow-list of tool-name patterns applied to every request routed through
+     * this pack (wildcards allowed). Kept only when no toolsAllow is set on the
+     * request itself; a request-level ?tools=/X-Proxy-Tools always wins.
+     */
+    toolsAllow?: string[];
+}
+
+/**
+ * Named OpenAI-compatible endpoints — N local/LAN model servers (Ollama,
+ * llama-server, vLLM, …) configured from a JSON file instead of one-off env
+ * vars. Mirrors the field names of `openagentik/router`'s `providers[]`
+ * schema (`kind`, `baseUrl`, `apiKeyEnv`, `defaultRequestFields`, `timeoutMs`)
+ * so a config is portable between the two — see
+ * `projects/openagentik/router/router.example.yaml` and
+ * `packages/core/src/config/schema.ts` in that repo.
+ *
+ * Deliberately dependency-free (no zod, no fs writes) and side-effect-free at
+ * import time, like packs.ts — this module is imported by both the proxy
+ * (src/index.ts) and the CLI (`agentproto llm endpoints …`), which must NOT
+ * pull in an HTTP server just to read/validate the config file.
+ */
+/** A JSON value — what `JSON.parse` can ever produce. */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** Arbitrary top-level OpenAI-compatible request fields, merged UNDER the
+ *  client's own request (see index.ts's applyDefaultRequestFields) —
+ *  everything from vLLM's `chat_template_kwargs` extension to a plain field
+ *  like LM Studio's `reasoning_effort`. See README's "Adding an
+ *  OpenAI-compatible upstream provider" section. */
+type EndpointDefaultRequestFields = Record<string, JsonValue>;
+interface EndpointTimeoutConfig {
+    /** Applied as the outbound socket timeout (time-to-first-byte). */
+    firstTokenMs?: number;
+}
+/**
+ * One configured endpoint. `kind` is carried (mirroring the router schema)
+ * but only `"openai"` is meaningful here — every routable endpoint in
+ * llm-endpoint speaks the OpenAI chat/completions wire shape, same as forge.
+ */
+interface EndpointConfig {
+    id: string;
+    kind: 'openai';
+    baseUrl: string;
+    /** Name of the env var holding the key — never the key itself. Absent ⇒
+     *  the endpoint is always keyless (a private/LAN server with no auth). */
+    apiKeyEnv?: string;
+    defaultRequestFields?: EndpointDefaultRequestFields;
+    timeoutMs?: EndpointTimeoutConfig;
+}
+interface ParsedEndpointsResult {
+    endpoints: EndpointConfig[];
+    errors: string[];
+}
+/**
+ * Validate the `{ endpoints: [...] }` envelope. Checks each entry's shape,
+ * plus duplicate ids — including against the implicit `forge` id, which a
+ * file entry may never reuse.
+ */
+declare function parseEndpointsConfig(parsed: unknown): ParsedEndpointsResult;
+/** `~/.agentproto/llm-endpoints.json`, overridable via `LLM_ENDPOINT_ENDPOINTS_FILE`. */
+declare function resolveEndpointsFilePath(): string;
+interface EndpointsFileLoad extends ParsedEndpointsResult {
+    path: string;
+}
+/**
+ * Read + validate the endpoints file from disk. A missing file is NOT an
+ * error (fail-soft, like packs.local.json) — it means "no named endpoints
+ * configured", which is the normal case. Malformed JSON or a shape error IS
+ * an error, and yields an empty endpoint list (fail closed on that file
+ * rather than partially trusting it).
+ */
+declare function readEndpointsFromDisk(path?: string): EndpointsFileLoad;
+/** Cached, validated endpoint list — re-read from disk on first call after
+ *  boot or after {@link resetConfiguredEndpointsCache}. A file-load error is
+ *  logged once and treated as "no endpoints configured" (fail-soft), mirroring
+ *  index.ts's getLocalPacks(). */
+declare function getConfiguredEndpoints(): EndpointConfig[];
+/** Drop the cached endpoint list so the next call re-reads the file. */
+declare function resetConfiguredEndpointsCache(): void;
+/** A resolved OpenAI-compatible upstream — host/port/protocol/path-prefix
+ *  parsed from a base URL. Shared shape for forge, nebius, and every
+ *  file-configured endpoint (see index.ts's ConfigurableProviderSpec). */
+interface ConfigurableUpstream {
+    hostname: string;
+    port: number;
+    protocol: 'http' | 'https';
+    /** URL pathname with any trailing slash stripped, e.g. "/v1" or "" for root. */
+    pathPrefix: string;
+}
+
+interface ToolTrimOptions {
+    provider: string;
+    queryTools: string | null;
+    queryNoTools: string | null;
+    headerTools: string | null;
+    headerNoTools: string | null;
+    headerExcludeTools: string | null;
+    /** Pack-level exclude patterns (pack.toolsExclude) — applied last. */
+    packToolsExclude?: string[];
+    /** Pack-level allow patterns (pack.toolsAllow) — applied last. */
+    packToolsAllow?: string[];
+}
+declare function trimTools(payload: any, opts: ToolTrimOptions): void;
+interface ProviderKeys {
+    anthropic: string;
+    moonshot: string;
+    openrouter: string;
+    requesty: string;
+    zai: string;
+    groq: string;
+    xai: string;
+    openai: string;
+}
+
+/** Back-compat name — see {@link ConfigurableUpstream}. */
+type ForgeUpstream = ConfigurableUpstream;
+/**
+ * Parse `FORGE_BASE_URL` into a routable upstream. Unlike every other
+ * provider here (fixed https hostname, implicit :443), forge points at a
+ * private, self-hosted OpenAI-compatible server (vLLM `--enable-lora`) so the
+ * scheme, host, port, and path prefix are all env-configured — e.g.
+ * `http://10.0.10.20:8000/v1`. Returns null when unset or malformed, which
+ * callers treat as "forge provider not configured" (a 400, never a crash).
+ */
+declare function resolveForgeBaseUrl(raw?: string | undefined): ConfigurableUpstream | null;
+/**
+ * Resolve the Nebius AI Studio upstream. Defaults to the public
+ * `https://api.studio.nebius.com/v1` endpoint — nebius works with just
+ * `NEBIUS_API_KEY` set. `NEBIUS_BASE_URL` overrides it, e.g. to point at a
+ * Nebius *dedicated* endpoint on a different host, with no code change.
+ * Returns null only when the override is set but malformed — an unset
+ * `NEBIUS_BASE_URL` is the normal case and resolves to the default.
+ */
+declare function resolveNebiusBaseUrl(raw?: string | undefined): ConfigurableUpstream | null;
+interface ModelRouteContext {
+    activePack: ModelPack;
+    queryModelCode: string | null;
+    queryProvider: string | null;
+    forcedAliasCode: string | null;
+    /**
+     * When true, the Messages path is allowed to match local-pack
+     * `equivalentClaudeName` aliases. The OpenAI chat/completions and Responses
+     * surfaces are always transparent and never resolve default alias packs.
+     */
+    allowAliases: boolean;
+    /**
+     * When true, the active pack has been run through {@link toAnthropicStyle}
+     * for this request, so its `equivalentClaudeName` aliases are resolvable even
+     * though it is an official (non-local) pack.
+     */
+    anthropicFormat?: boolean;
+}
+/**
+ * Resolves the upstream provider/model for a request.
+ *
+ * Messages path (`allowAliases: true`):
+ *   - X-Proxy-Model-Alias header / PROXY_MODEL_ALIAS env forces a pack code.
+ *   - Explicit ?m=<code> selects a pack code.
+ *   - Local packs may define `equivalentClaudeName` aliases.
+ *   - Public pack codes match transparent model IDs.
+ *   - `provider/model` references are parsed transparently.
+ *   - `?p=<provider>` with a bare model id routes to that provider.
+ *
+ * Chat/Responses paths (`allowAliases: false`):
+ *   - Only `provider/model` references or `?p=<provider>` with a bare model id.
+ *   - Pack aliases and regex fallbacks are intentionally not used.
+ *
+ * Throws a plain Error for unknown explicit codes/providers.
+ */
+declare function resolveModelRoute(payload: {
+    model?: string;
+}, ctx: ModelRouteContext, localPacks?: Record<string, ModelPack>): {
+    provider: string;
+    model: string;
+};
+type UpstreamAuthMethod = 'api-key' | 'oauth-bearer';
+/** A resolved upstream credential: the secret plus the header shape to use. */
+interface UpstreamCredential {
+    value: string;
+    method: UpstreamAuthMethod;
+}
+/**
+ * Resolve the outbound credential for `provider`. Mirrors getApiKey()'s
+ * provider-string contract but returns the credential AND the header method.
+ *
+ * - `LLM_ENDPOINT_PROFILE_<P>` set → resolve the named profile:
+ *     • missing / disabled          → undefined (caller 401s, as today)
+ *     • source-backed (no credRef)  → undefined + a clear follow-up log
+ *                                      (self-refresh not supported here yet)
+ *     • credentialRef-backed        → { value, method: profile.method }
+ *     • keychain read returns null (credential absent / present-but-unreadable
+ *       on a supported host, e.g. a locked Keychain) → undefined (fail-closed;
+ *       caller 401s — we do NOT silently downgrade a mapped profile to the env
+ *       key)
+ *     • keychain read throws (platform-unsupported backend, e.g. non-darwin
+ *       host) → env-key fallback + a one-time log; never crashes the request
+ * - no mapping → env-key path: method is derived from the credential's own
+ *   shape, not hardcoded — an anthropic env key that is actually a
+ *   subscription OAT (`sk-ant-oat…`, e.g. injected by the runtime's
+ *   billing-auth resolver for a modelDerivedApiKey adapter with no
+ *   `authSubscription`, such as pi) resolves to "oauth-bearer" so
+ *   {@link buildUpstreamAuthHeaders} sends it as `Authorization: Bearer`
+ *   instead of `x-api-key` — Anthropic hard-401s an OAT presented as
+ *   `x-api-key` ("invalid x-api-key"). Any other anthropic key, and every
+ *   other provider, keeps "api-key" exactly as before.
+ */
+declare function resolveUpstreamCredential(provider: string): Promise<UpstreamCredential | undefined>;
+/**
+ * Single source of truth for the outbound upstream-auth header shape. Given a
+ * resolved credential, returns the auth-related headers to merge into the
+ * request. For an `api-key` credential each provider keeps its existing header
+ * exactly; for `oauth-bearer` (only meaningful on the anthropic upstream) it
+ * emits the Bearer + anthropic-version + anthropic-beta triple.
+ *
+ * Fail-closed: an `oauth-bearer` credential (e.g. a Claude subscription OAT)
+ * resolved for a NON-anthropic provider returns `null` — the token is never
+ * emitted to a third-party upstream. Callers MUST treat `null` as a hard 401
+ * and send no request.
+ */
+declare function buildUpstreamAuthHeaders(provider: string, cred: UpstreamCredential): Record<string, string> | null;
+/**
+ * Fail-closed guard for the OpenAI-compatible surfaces (/v1/responses,
+ * /v1/chat/completions). Those surfaces are ALWAYS non-anthropic
+ * (getChatCompletionsEndpoint returns null for anthropic) and forward the
+ * resolved credential as `Authorization: Bearer <value>` — so only an
+ * `api-key` credential may be used. A subscription/oauth credential (e.g. a
+ * Claude OAT) must be rejected, never leaked to a third-party host.
+ *
+ * Returns true when the credential may proceed on this surface. An absent
+ * credential returns true here (the caller's missing-key check 401s it).
+ */
+declare function isCredentialAllowedOnOpenAiSurface(cred: UpstreamCredential | undefined): boolean;
+declare const CANONICAL_UPSTREAMS: (keyof ProviderKeys)[];
+/** Narrow an arbitrary provider string to one of the canonical upstreams. */
+declare function isCanonicalUpstream(provider: string): provider is keyof ProviderKeys;
+/** How a credential WOULD resolve for an upstream (never leaks the value). */
+type UpstreamSource = 'profile' | 'env' | 'none';
+/**
+ * Non-secret status of one upstream's outbound credential:
+ *  - `linkedProfile`: the `LLM_ENDPOINT_PROFILE_<P>` profile id, or null.
+ *  - `source`: how a credential would resolve — a mapped profile ("profile",
+ *    even if that profile is missing/disabled), else a non-empty per-provider
+ *    env key ("env"), else "none".
+ *  - `method`: the outbound auth shape — the mapped profile's method, or
+ *    "api-key" for the env path, or null when nothing is configured.
+ *  - `present`: whether a credential actually resolves. Known for free for the
+ *    env ("env" ⇒ true) and none ("none" ⇒ false) sources; for a profile source
+ *    it is `null` unless `?probe=1` was requested, because confirming it reads
+ *    the OS keychain (one read per mapped profile).
+ */
+interface UpstreamStatus {
+    provider: string;
+    linkedProfile: string | null;
+    source: UpstreamSource;
+    method: UpstreamAuthMethod | null;
+    present: boolean | null;
+}
+/**
+ * Describe one upstream's credential status without returning a secret. The
+ * default (mapping-only) view is cheap — an env-var read plus, for a mapped
+ * provider, one auth-profiles.json read for the method. `present` for a profile
+ * source is filled only when `opts.probe` is set (it costs a keychain read).
+ */
+declare function describeUpstreamStatus(provider: string, opts: {
+    probe: boolean;
+}): Promise<UpstreamStatus>;
+/** Status for all 8 canonical upstreams, in ProviderKeys order. */
+declare function collectUpstreamStatuses(opts: {
+    probe: boolean;
+}): Promise<UpstreamStatus[]>;
+/** The result of a per-upstream live test — a verdict, or "no cheap probe". */
+type UpstreamTestResult = {
+    ok: boolean;
+    status: number;
+    detail: string;
+} | {
+    ok: null;
+    reason: 'no-probe';
+};
+/**
+ * Run the cheapest authenticated call for `provider` and return a verdict.
+ * Resolves the credential through the same precedence as a real request, then
+ * uses buildUpstreamAuthHeaders for the exact per-provider header shape — so an
+ * oauth-bearer credential mis-mapped to a non-anthropic upstream is refused
+ * (never forwarded) rather than tested.
+ */
+declare function testUpstream(provider: string): Promise<UpstreamTestResult>;
+declare function stripThinkingFromAnthropicJson(jsonStr: string): string;
+declare function resolveEmptyTurnRetries(): number;
+/**
+ * True when an Anthropic Messages JSON body is a "tour vide": ended normally
+ * (`end_turn`) but carries no client-visible content once thinking is stripped.
+ */
+declare function isEmptyAnthropicTurn(jsonStr: string): boolean;
+declare function openaiJsonToAnthropic(jsonStr: string): string;
+/** Parse a comma-separated token allow-list into a Set (trimmed, non-empty). */
+declare function parseAccessTokens(raw: string | undefined): Set<string>;
+/**
+ * Extract a presented access token from `Authorization: Bearer <t>` or the
+ * `X-Proxy-Access: <t>` header (so a client that reserves Authorization for
+ * something else can still pass one). Returns null when neither is present.
+ */
+declare function extractInboundToken(headers: IncomingMessage['headers']): string | null;
+/**
+ * True when the request may proceed: gate disabled (empty allow-list), or the
+ * presented token is in the allow-list. A high-entropy random token makes the
+ * Set membership check's non-constant time immaterial.
+ */
+declare function isAuthorized(headers: IncomingMessage['headers'], tokens: Set<string>): boolean;
+/**
+ * Extract a presented edge token from the `X-Edge-Auth: <t>` header. Returns
+ * null when absent or blank.
+ */
+declare function extractEdgeToken(headers: IncomingMessage['headers']): string | null;
+/**
+ * True when the request may proceed through the edge/WAF layer: layer
+ * disabled (empty allow-list), or the presented `X-Edge-Auth` token is in the
+ * allow-list.
+ */
+declare function isEdgeAuthorized(headers: IncomingMessage['headers'], edgeTokensSet: Set<string>): boolean;
+/**
+ * Builds a Cloudflare custom-rule (wirefilter) expression that BLOCKS any
+ * request lacking a valid token, for the header (`authorization` or
+ * `x-edge-auth`) matching the layer being enforced at the edge. Intended to
+ * be pasted into a Cloudflare custom rule so the token check happens before
+ * traffic ever reaches this process — the `edgeTokens()`/`isEdgeAuthorized`
+ * pair above is the same policy enforced in-process as a fallback.
+ *
+ * CORS preflight (`OPTIONS`) is always allowed through so the browser's
+ * preflight — which cannot carry the token — isn't blocked.
+ */
+declare function buildWafRuleExpression(opts: {
+    host?: string;
+    tokens: string[];
+    header: 'authorization' | 'x-edge-auth';
+}): string;
+/**
+ * Normalise an incoming request path so a redundant `/v1` an Anthropic client
+ * appends to a base URL that already ends in `/v1` (optionally with a pack
+ * segment) doesn't break routing.
+ *
+ *   /v1/v1/messages                    → /v1/messages
+ *   /v1/stealth-requesty/v1/messages   → /v1/stealth-requesty/messages
+ *   /v1/stealth-requesty/v1/models     → /v1/stealth-requesty/models
+ *
+ * Without the pack-segment case the extra `/v1` breaks the `/v1/<pack>/<verb>`
+ * match, the pack is silently lost, and the request falls back to the default
+ * pack — the "no usable models" / "Unable to resolve model" failure a client
+ * configured with `base_url = .../v1/<pack>` hits.
+ */
+declare function normalizeProxyPath(pathname: string): string;
+/**
+ * True only for the DEFAULT model-discovery path — `/v1/models` or `/models`,
+ * never a pack-scoped list (`/v1/<pack>/models`). Lets opt-in public discovery
+ * expose the default codename list without disclosing pack names.
+ */
+declare function isPublicModelListPath(pathname: string): boolean;
+declare const server: node_http.Server<typeof IncomingMessage, typeof ServerResponse>;
+
+/** Démarre le proxy sur `port` (défaut : {@link PORT}). Renvoie le serveur en écoute. */
+declare function start(port?: number): node_http.Server<typeof IncomingMessage, typeof ServerResponse>;
+
+export { CANONICAL_UPSTREAMS, type ConfigurableUpstream, type EndpointConfig, type EndpointDefaultRequestFields, type EndpointsFileLoad, type ForgeUpstream, type ModelRouteContext, type ToolTrimOptions, type UpstreamCredential, type UpstreamSource, type UpstreamStatus, type UpstreamTestResult, buildUpstreamAuthHeaders, buildWafRuleExpression, collectUpstreamStatuses, describeUpstreamStatus, extractEdgeToken, extractInboundToken, getConfiguredEndpoints, isAuthorized, isCanonicalUpstream, isCredentialAllowedOnOpenAiSurface, isEdgeAuthorized, isEmptyAnthropicTurn, isPublicModelListPath, normalizeProxyPath, openaiJsonToAnthropic, parseAccessTokens, parseEndpointsConfig, readEndpointsFromDisk, resetConfiguredEndpointsCache, resolveEmptyTurnRetries, resolveEndpointsFilePath, resolveForgeBaseUrl, resolveModelRoute, resolveNebiusBaseUrl, resolveUpstreamCredential, server, start, stripThinkingFromAnthropicJson, testUpstream, trimTools };