@omnicross/core 0.1.0

package/dist/outbound-api.d.cts

@@ -0,0 +1,320 @@
+import { E as EndpointRoutingConfig, a as OutboundApiDeps, e as OutboundApiServerStatus, g as OutboundFormatUrls, d as OutboundApiServerConfig, O as OutboundKeyDb, b as OutboundApiKeyCreated, R as RequestRole, f as OutboundEndpoint } from './types-CGGrKqC_.cjs';
+export { c as OutboundApiKeyInfo, h as OutboundKeyDbRow } from './types-CGGrKqC_.cjs';
+import { I as IngressFormat, P as ProviderConfigSource, g as RouteContext } from './types-DZIQbgp0.cjs';
+import { SubscriptionProviderId } from '@omnicross/contracts/subscription-types';
+import './ProviderProxy-f_8ziIhW.cjs';
+import 'node:http';
+import '@omnicross/contracts/completion-types';
+import '@omnicross/contracts/usage-types';
+import './ApiKeyPoolService-BmMkau07.cjs';
+import '@omnicross/contracts/llm-config';
+import './SubscriptionAuthSource-Cr4fVEYY.cjs';
+import './pipeline/SubscriptionAuthStrategy.cjs';
+import './transformer/types.cjs';
+import './transformer/TransformerService.cjs';
+import '@omnicross/contracts/websearch-types';
+
+/**
+ * OutboundApiServer — the external-facing HTTP listener for the outbound API
+ * server (`outbound-api-server`, design D1/D4/D5).
+ *
+ * A SEPARATE long-lived `http.Server` (distinct from the resident loopback
+ * `ProviderProxy`). It binds `127.0.0.1` by default, or `0.0.0.0` when network
+ * binding is enabled. Every request — INCLUDING loopback — is authenticated by
+ * a named API key (no loopback bypass). Each authenticated request mints a route
+ * on the SHARED `ProviderProxyRouteMap` and delegates to the existing
+ * `routeRequest()` dispatch so the four ingress parsers + transformer are
+ * reused (one conversion stack).
+ *
+ * Lifecycle:
+ *  - `applyConfig({ enabled, networkBinding, endpoints, port })` — restart ONLY
+ *    when the bind address or port changes; per-endpoint routing config is read
+ *    live per request (no restart).
+ *  - `getStatus()` — running, actual port, loopback + optional LAN URLs, the
+ *    four format URLs.
+ *  - `EADDRINUSE` → fall back to an ephemeral port, persist it (via the caller's
+ *    `onPortChange`), and surface the actual port.
+ *
+ * @module outbound-api/OutboundApiServer
+ */
+
+/** Fixed default port (design D5). Persisted + configurable. */
+declare const DEFAULT_OUTBOUND_PORT = 8765;
+/** Per-call apply config (the persisted server config minus runtime state). */
+interface ApplyConfigInput {
+    enabled: boolean;
+    networkBinding: boolean;
+    endpoints: EndpointRoutingConfig[];
+    port?: number;
+}
+declare class OutboundApiServer {
+    private readonly deps;
+    /** Called when the actual bound port differs from the requested one. */
+    private readonly onPortChange?;
+    private server;
+    private boundPort;
+    private boundAddr;
+    private endpoints;
+    private readonly rateLimiter;
+    constructor(deps: OutboundApiDeps, 
+    /** Called when the actual bound port differs from the requested one. */
+    onPortChange?: ((port: number) => void) | undefined);
+    /**
+     * Apply a config. Restarts the listener ONLY when the bind address or port
+     * changes (or when toggling enabled); per-endpoint routing config is updated
+     * in place (read live per request — no restart).
+     */
+    applyConfig(input: ApplyConfigInput): Promise<void>;
+    /** Start the listener on `bindAddr:port`, falling back on EADDRINUSE. */
+    start(bindAddr: string, port: number): Promise<number>;
+    /** Bind once; on EADDRINUSE retry with an ephemeral port (port 0). */
+    private listen;
+    /** Per-request handler. Auth is enforced on EVERY request (incl. loopback). */
+    private onRequest;
+    /** Stop the listener and release the port. */
+    stop(): Promise<void>;
+    /** A live status snapshot for the Settings tab. */
+    getStatus(): OutboundApiServerStatus;
+}
+/** Build the four format endpoint URLs for a base URL. */
+declare function formatUrls(base: string): OutboundFormatUrls;
+
+/**
+ * apiServerConfig — load / save / default the outbound API server config
+ * (`outbound-api-server`, design D4).
+ *
+ * The config (`{ enabled, networkBinding, endpoints, port }`) is persisted via
+ * a small key/value store (the app SettingsService) under a single key, so it
+ * survives restart. Defaults: disabled, loopback, four endpoints with empty
+ * models + `useSubscription` OFF, default port. Shared by the router and the
+ * bootstrap wiring so both read/write the same shape.
+ *
+ * @module outbound-api/apiServerConfig
+ */
+
+/** The settings key the config persists under. */
+declare const OUTBOUND_API_SERVER_CONFIG_KEY = "outboundApiServer.config";
+/** Structural subset of the settings store the config loader needs. */
+interface ApiServerSettingsStore {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T): Promise<void>;
+}
+/** The default server config: disabled, loopback, four blank endpoints. */
+declare function defaultServerConfig(): OutboundApiServerConfig;
+/**
+ * Normalize a (possibly partial / legacy) persisted config to the full shape:
+ * ensure all four endpoints exist, `useSubscription` defaults OFF, and a port
+ * is present.
+ */
+declare function normalizeServerConfig(raw: Partial<OutboundApiServerConfig> | undefined | null): OutboundApiServerConfig;
+/** Load the persisted config (normalized), defaulting on a missing/blank key. */
+declare function loadServerConfig(store: ApiServerSettingsStore): Promise<OutboundApiServerConfig>;
+/** Persist the config. */
+declare function saveServerConfig(store: ApiServerSettingsStore, config: OutboundApiServerConfig): Promise<void>;
+/** Apply a partial patch to a config, returning the merged whole. */
+declare function mergeServerConfig(current: OutboundApiServerConfig, patch: Partial<OutboundApiServerConfig>): OutboundApiServerConfig;
+
+/**
+ * outboundApiKeyAuth — named-key generation, hashing, and verification for the
+ * outbound API server (`outbound-api-server`).
+ *
+ * Keys are 128-bit+ random secrets (`sk-omnicross-<base62>`), NOT human passwords,
+ * so a single fast hash (sha256) is sufficient and keeps the hot auth path
+ * cheap (design D3). Only the hash + a short display prefix are persisted; the
+ * full plaintext is returned exactly once at creation.
+ *
+ * @module outbound-api/outboundApiKeyAuth
+ */
+
+/** Hash a presented/generated secret (sha256 hex). */
+declare function hashKey(secret: string): string;
+/**
+ * Create + persist a named key. Returns the plaintext ONCE; only the hash +
+ * prefix are stored.
+ */
+declare function createNamedKey(db: OutboundKeyDb, name: string): Promise<OutboundApiKeyCreated>;
+/** The id of a verified key (for rate-limiting + last-used bookkeeping). */
+interface VerifiedKey {
+    id: string;
+}
+/**
+ * Verify a presented key against the DB. Matches by hash where the stored row
+ * is enabled AND not revoked (the DB query enforces this). On success bumps
+ * `lastUsedAt` (best-effort, fire-and-forget) and returns the key id; returns
+ * `null` on any miss / disabled / revoked key.
+ */
+declare function verifyPresentedKey(db: OutboundKeyDb, presentedKey: string | undefined): Promise<VerifiedKey | null>;
+
+/**
+ * outboundRateLimiter — per-API-key in-memory sliding-window rate limiter for
+ * the outbound API server (`outbound-api-server`, design D6).
+ *
+ * A simple fixed-size sliding window keyed by `apiKeyId`. In-memory only (resets
+ * on app restart, acceptable for v1). Exceeding the limit returns a deny with a
+ * `Retry-After` (seconds). Limits are conservative defaults, not user-
+ * configurable in v1.
+ *
+ * @module outbound-api/outboundRateLimiter
+ */
+interface RateLimitDecision {
+    allowed: boolean;
+    /** Seconds until the window frees up (only meaningful when `!allowed`). */
+    retryAfterSeconds: number;
+}
+interface RateLimiterOptions {
+    windowMs?: number;
+    maxRequests?: number;
+}
+/**
+ * Per-key sliding-window limiter. `check(apiKeyId)` records the request and
+ * returns whether it is allowed.
+ */
+declare class OutboundRateLimiter {
+    private readonly windowMs;
+    private readonly maxRequests;
+    /** apiKeyId → ascending request timestamps within the current window. */
+    private readonly hits;
+    constructor(options?: RateLimiterOptions);
+    /**
+     * Record a request for `apiKeyId` and decide whether it is allowed. Prunes
+     * timestamps older than the window first; when allowed, the request's
+     * timestamp is appended.
+     */
+    check(apiKeyId: string, now?: number): RateLimitDecision;
+    /** Drop all recorded state (tests / teardown). */
+    reset(): void;
+}
+
+/**
+ * roleDetection — classify an outbound request's ROLE (vision / background /
+ * default) so the route resolver can pick the endpoint's model for that role
+ * (`outbound-api-server`, design D2).
+ *
+ * Precedence: vision > background > default.
+ *  - vision      — the body carries image/vision content parts (per-format
+ *                  detection). The route resolver applies the vision→default
+ *                  fallback when the endpoint has no vision model.
+ *  - background  — the requested model id is in the endpoint's optional
+ *                  background-model-id override list (human decision after the
+ *                  proposal), OR the registry small/haiku-class name signal
+ *                  matches (Claude Code's haiku probe sends exactly this).
+ *  - default     — everything else.
+ *
+ * Each ingress's body shape is handled here in ONE place.
+ *
+ * @module outbound-api/roleDetection
+ */
+
+/**
+ * Detect the request's role. `backgroundModelIds` is the endpoint's optional
+ * override list: when an incoming requested model id matches an entry there, the
+ * request is BACKGROUND regardless of the name signal; otherwise the registry
+ * small/haiku-class name signal is the baseline. Precedence vision > background
+ * > default.
+ */
+declare function detectRequestRole(ingressFormat: IngressFormat, body: Record<string, unknown>, options?: {
+    backgroundModelIds?: string[];
+}): RequestRole;
+/** Map a settings endpoint id to the provider-proxy ingress format. */
+declare function endpointToIngressFormat(endpoint: 'chat' | 'responses' | 'messages' | 'gemini'): IngressFormat;
+
+/**
+ * subscriptionSupport — single source of truth for (a) which provider ids are
+ * subscription-backed and (b) which outbound endpoints can soundly serve a
+ * subscription route (`outbound-api-server`, design D2 + review M1/m1).
+ *
+ * The subscription-id catalog mirrors `SubscriptionProviderRegistry`'s ids; the
+ * static fast-path is backstopped at runtime by a live registry lookup (see
+ * `isSubscriptionProviderId`) so it degrades gracefully if it drifts. Both
+ * `routeResolver` and `apiServerHandlers` import from here — no duplicated set.
+ *
+ * @module outbound-api/subscriptionSupport
+ */
+
+/**
+ * The registry-aligned subscription provider ids — the outbound layer's SSOT
+ * fast-path. NOTE: `SubscriptionProviderId` is currently a `z.string()` alias,
+ * so this `readonly SubscriptionProviderId[]` typing does NOT compile-enforce
+ * alignment with the registry; drift is instead tolerated at runtime by
+ * `isSubscriptionProviderId`'s live `registry.getProfile` fallback.
+ */
+declare const SUBSCRIPTION_PROVIDER_IDS: readonly SubscriptionProviderId[];
+/**
+ * True when a provider id refers to a subscription-backed provider. Checks the
+ * registry-aligned static catalog first, then falls back to a live registry
+ * lookup (so a registry addition is honored even before this list is updated).
+ *
+ * NOTE (review m2): this classifies by id string. The resolver MUST confirm the
+ * id does not resolve to a real BYO provider row before treating it as
+ * subscription-backed — see `routeResolver` (BYO rows win).
+ */
+declare function isSubscriptionProviderId(providerId: string): boolean;
+/** True when the endpoint's ingress can soundly serve a subscription route. */
+declare function endpointSupportsSubscription(endpoint: OutboundEndpoint): boolean;
+
+/**
+ * routeResolver — turn an endpoint's `EndpointRoutingConfig` + the detected
+ * request role into a `RouteContext` for the shared `provider-proxy` dispatch
+ * (`outbound-api-server`, design D2).
+ *
+ * Steps:
+ *  1. Pick the model for the role (vision → default fallback when `visionModel`
+ *     is unset; vision is optional).
+ *  2. Parse the chosen `"providerId,modelId"` ref.
+ *  3. Gate by `useSubscription`: OFF → only BYO-key providers are eligible
+ *     (subscription-backed providers excluded); ON → subscription-backed
+ *     providers are eligible.
+ *  4. Resolve the provider (BYO via the `ProviderConfigSource`; subscription via the
+ *     subscription registry) and build the `RouteContext` exactly as the
+ *     internal callers do.
+ *  5. Return a clear `503`-style error when the role's required model is unset,
+ *     the provider is unavailable, or the subscription gate excludes it.
+ *
+ * @module outbound-api/routeResolver
+ */
+
+/** A 503-style resolution failure. */
+interface RouteResolveError {
+    status: number;
+    message: string;
+}
+type RouteResolveResult = {
+    ok: true;
+    route: RouteContext;
+    usedRole: RequestRole;
+} | {
+    ok: false;
+    error: RouteResolveError;
+};
+/** Resolve a route for one authenticated outbound request. */
+declare function resolveRoute(args: {
+    config: EndpointRoutingConfig;
+    role: RequestRole;
+    ingressFormat: IngressFormat;
+    llmConfig: ProviderConfigSource;
+    sessionId?: string | null;
+}): Promise<RouteResolveResult>;
+
+/**
+ * Outbound API server module — barrel + singleton accessor.
+ *
+ * The outbound server is constructed ONCE at app bootstrap (sharing the
+ * resident `ProviderProxy`'s route map + deps) and started only when the
+ * persisted `enabled` setting is true. `getOutboundApiServer(deps)` mirrors
+ * `getProviderProxy()`: the first call constructs the instance from the supplied
+ * deps; later calls return it.
+ *
+ * @module outbound-api/index
+ */
+
+/**
+ * Get (or lazily construct) the outbound API server singleton.
+ *
+ * @param deps Required on the FIRST call (app bootstrap). Ignored afterward.
+ * @param onPortChange Optional persistence hook for the EADDRINUSE fallback.
+ */
+declare function getOutboundApiServer(deps?: OutboundApiDeps, onPortChange?: (port: number) => void): OutboundApiServer;
+/** Reset the singleton (tests / teardown only). */
+declare function __resetOutboundApiServerForTests(): void;
+
+export { type ApiServerSettingsStore, type ApplyConfigInput, DEFAULT_OUTBOUND_PORT, EndpointRoutingConfig, OUTBOUND_API_SERVER_CONFIG_KEY, OutboundApiDeps, OutboundApiKeyCreated, OutboundApiServer, OutboundApiServerConfig, OutboundApiServerStatus, OutboundEndpoint, OutboundFormatUrls, OutboundKeyDb, OutboundRateLimiter, RequestRole, SUBSCRIPTION_PROVIDER_IDS, __resetOutboundApiServerForTests, createNamedKey, defaultServerConfig, detectRequestRole, endpointSupportsSubscription, endpointToIngressFormat, formatUrls, getOutboundApiServer, hashKey, isSubscriptionProviderId, loadServerConfig, mergeServerConfig, normalizeServerConfig, resolveRoute, saveServerConfig, verifyPresentedKey };

package/dist/outbound-api.d.ts

@@ -0,0 +1,320 @@
+import { E as EndpointRoutingConfig, a as OutboundApiDeps, e as OutboundApiServerStatus, g as OutboundFormatUrls, d as OutboundApiServerConfig, O as OutboundKeyDb, b as OutboundApiKeyCreated, R as RequestRole, f as OutboundEndpoint } from './types-CbCN2NQP.js';
+export { c as OutboundApiKeyInfo, h as OutboundKeyDbRow } from './types-CbCN2NQP.js';
+import { I as IngressFormat, P as ProviderConfigSource, g as RouteContext } from './types-DCzHkhJt.js';
+import { SubscriptionProviderId } from '@omnicross/contracts/subscription-types';
+import './ProviderProxy-vjt8sQQk.js';
+import 'node:http';
+import '@omnicross/contracts/completion-types';
+import '@omnicross/contracts/usage-types';
+import './ApiKeyPoolService-BmMkau07.js';
+import '@omnicross/contracts/llm-config';
+import './SubscriptionAuthSource-D89zmiSS.js';
+import './pipeline/SubscriptionAuthStrategy.js';
+import './transformer/types.js';
+import './transformer/TransformerService.js';
+import '@omnicross/contracts/websearch-types';
+
+/**
+ * OutboundApiServer — the external-facing HTTP listener for the outbound API
+ * server (`outbound-api-server`, design D1/D4/D5).
+ *
+ * A SEPARATE long-lived `http.Server` (distinct from the resident loopback
+ * `ProviderProxy`). It binds `127.0.0.1` by default, or `0.0.0.0` when network
+ * binding is enabled. Every request — INCLUDING loopback — is authenticated by
+ * a named API key (no loopback bypass). Each authenticated request mints a route
+ * on the SHARED `ProviderProxyRouteMap` and delegates to the existing
+ * `routeRequest()` dispatch so the four ingress parsers + transformer are
+ * reused (one conversion stack).
+ *
+ * Lifecycle:
+ *  - `applyConfig({ enabled, networkBinding, endpoints, port })` — restart ONLY
+ *    when the bind address or port changes; per-endpoint routing config is read
+ *    live per request (no restart).
+ *  - `getStatus()` — running, actual port, loopback + optional LAN URLs, the
+ *    four format URLs.
+ *  - `EADDRINUSE` → fall back to an ephemeral port, persist it (via the caller's
+ *    `onPortChange`), and surface the actual port.
+ *
+ * @module outbound-api/OutboundApiServer
+ */
+
+/** Fixed default port (design D5). Persisted + configurable. */
+declare const DEFAULT_OUTBOUND_PORT = 8765;
+/** Per-call apply config (the persisted server config minus runtime state). */
+interface ApplyConfigInput {
+    enabled: boolean;
+    networkBinding: boolean;
+    endpoints: EndpointRoutingConfig[];
+    port?: number;
+}
+declare class OutboundApiServer {
+    private readonly deps;
+    /** Called when the actual bound port differs from the requested one. */
+    private readonly onPortChange?;
+    private server;
+    private boundPort;
+    private boundAddr;
+    private endpoints;
+    private readonly rateLimiter;
+    constructor(deps: OutboundApiDeps, 
+    /** Called when the actual bound port differs from the requested one. */
+    onPortChange?: ((port: number) => void) | undefined);
+    /**
+     * Apply a config. Restarts the listener ONLY when the bind address or port
+     * changes (or when toggling enabled); per-endpoint routing config is updated
+     * in place (read live per request — no restart).
+     */
+    applyConfig(input: ApplyConfigInput): Promise<void>;
+    /** Start the listener on `bindAddr:port`, falling back on EADDRINUSE. */
+    start(bindAddr: string, port: number): Promise<number>;
+    /** Bind once; on EADDRINUSE retry with an ephemeral port (port 0). */
+    private listen;
+    /** Per-request handler. Auth is enforced on EVERY request (incl. loopback). */
+    private onRequest;
+    /** Stop the listener and release the port. */
+    stop(): Promise<void>;
+    /** A live status snapshot for the Settings tab. */
+    getStatus(): OutboundApiServerStatus;
+}
+/** Build the four format endpoint URLs for a base URL. */
+declare function formatUrls(base: string): OutboundFormatUrls;
+
+/**
+ * apiServerConfig — load / save / default the outbound API server config
+ * (`outbound-api-server`, design D4).
+ *
+ * The config (`{ enabled, networkBinding, endpoints, port }`) is persisted via
+ * a small key/value store (the app SettingsService) under a single key, so it
+ * survives restart. Defaults: disabled, loopback, four endpoints with empty
+ * models + `useSubscription` OFF, default port. Shared by the router and the
+ * bootstrap wiring so both read/write the same shape.
+ *
+ * @module outbound-api/apiServerConfig
+ */
+
+/** The settings key the config persists under. */
+declare const OUTBOUND_API_SERVER_CONFIG_KEY = "outboundApiServer.config";
+/** Structural subset of the settings store the config loader needs. */
+interface ApiServerSettingsStore {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T): Promise<void>;
+}
+/** The default server config: disabled, loopback, four blank endpoints. */
+declare function defaultServerConfig(): OutboundApiServerConfig;
+/**
+ * Normalize a (possibly partial / legacy) persisted config to the full shape:
+ * ensure all four endpoints exist, `useSubscription` defaults OFF, and a port
+ * is present.
+ */
+declare function normalizeServerConfig(raw: Partial<OutboundApiServerConfig> | undefined | null): OutboundApiServerConfig;
+/** Load the persisted config (normalized), defaulting on a missing/blank key. */
+declare function loadServerConfig(store: ApiServerSettingsStore): Promise<OutboundApiServerConfig>;
+/** Persist the config. */
+declare function saveServerConfig(store: ApiServerSettingsStore, config: OutboundApiServerConfig): Promise<void>;
+/** Apply a partial patch to a config, returning the merged whole. */
+declare function mergeServerConfig(current: OutboundApiServerConfig, patch: Partial<OutboundApiServerConfig>): OutboundApiServerConfig;
+
+/**
+ * outboundApiKeyAuth — named-key generation, hashing, and verification for the
+ * outbound API server (`outbound-api-server`).
+ *
+ * Keys are 128-bit+ random secrets (`sk-omnicross-<base62>`), NOT human passwords,
+ * so a single fast hash (sha256) is sufficient and keeps the hot auth path
+ * cheap (design D3). Only the hash + a short display prefix are persisted; the
+ * full plaintext is returned exactly once at creation.
+ *
+ * @module outbound-api/outboundApiKeyAuth
+ */
+
+/** Hash a presented/generated secret (sha256 hex). */
+declare function hashKey(secret: string): string;
+/**
+ * Create + persist a named key. Returns the plaintext ONCE; only the hash +
+ * prefix are stored.
+ */
+declare function createNamedKey(db: OutboundKeyDb, name: string): Promise<OutboundApiKeyCreated>;
+/** The id of a verified key (for rate-limiting + last-used bookkeeping). */
+interface VerifiedKey {
+    id: string;
+}
+/**
+ * Verify a presented key against the DB. Matches by hash where the stored row
+ * is enabled AND not revoked (the DB query enforces this). On success bumps
+ * `lastUsedAt` (best-effort, fire-and-forget) and returns the key id; returns
+ * `null` on any miss / disabled / revoked key.
+ */
+declare function verifyPresentedKey(db: OutboundKeyDb, presentedKey: string | undefined): Promise<VerifiedKey | null>;
+
+/**
+ * outboundRateLimiter — per-API-key in-memory sliding-window rate limiter for
+ * the outbound API server (`outbound-api-server`, design D6).
+ *
+ * A simple fixed-size sliding window keyed by `apiKeyId`. In-memory only (resets
+ * on app restart, acceptable for v1). Exceeding the limit returns a deny with a
+ * `Retry-After` (seconds). Limits are conservative defaults, not user-
+ * configurable in v1.
+ *
+ * @module outbound-api/outboundRateLimiter
+ */
+interface RateLimitDecision {
+    allowed: boolean;
+    /** Seconds until the window frees up (only meaningful when `!allowed`). */
+    retryAfterSeconds: number;
+}
+interface RateLimiterOptions {
+    windowMs?: number;
+    maxRequests?: number;
+}
+/**
+ * Per-key sliding-window limiter. `check(apiKeyId)` records the request and
+ * returns whether it is allowed.
+ */
+declare class OutboundRateLimiter {
+    private readonly windowMs;
+    private readonly maxRequests;
+    /** apiKeyId → ascending request timestamps within the current window. */
+    private readonly hits;
+    constructor(options?: RateLimiterOptions);
+    /**
+     * Record a request for `apiKeyId` and decide whether it is allowed. Prunes
+     * timestamps older than the window first; when allowed, the request's
+     * timestamp is appended.
+     */
+    check(apiKeyId: string, now?: number): RateLimitDecision;
+    /** Drop all recorded state (tests / teardown). */
+    reset(): void;
+}
+
+/**
+ * roleDetection — classify an outbound request's ROLE (vision / background /
+ * default) so the route resolver can pick the endpoint's model for that role
+ * (`outbound-api-server`, design D2).
+ *
+ * Precedence: vision > background > default.
+ *  - vision      — the body carries image/vision content parts (per-format
+ *                  detection). The route resolver applies the vision→default
+ *                  fallback when the endpoint has no vision model.
+ *  - background  — the requested model id is in the endpoint's optional
+ *                  background-model-id override list (human decision after the
+ *                  proposal), OR the registry small/haiku-class name signal
+ *                  matches (Claude Code's haiku probe sends exactly this).
+ *  - default     — everything else.
+ *
+ * Each ingress's body shape is handled here in ONE place.
+ *
+ * @module outbound-api/roleDetection
+ */
+
+/**
+ * Detect the request's role. `backgroundModelIds` is the endpoint's optional
+ * override list: when an incoming requested model id matches an entry there, the
+ * request is BACKGROUND regardless of the name signal; otherwise the registry
+ * small/haiku-class name signal is the baseline. Precedence vision > background
+ * > default.
+ */
+declare function detectRequestRole(ingressFormat: IngressFormat, body: Record<string, unknown>, options?: {
+    backgroundModelIds?: string[];
+}): RequestRole;
+/** Map a settings endpoint id to the provider-proxy ingress format. */
+declare function endpointToIngressFormat(endpoint: 'chat' | 'responses' | 'messages' | 'gemini'): IngressFormat;
+
+/**
+ * subscriptionSupport — single source of truth for (a) which provider ids are
+ * subscription-backed and (b) which outbound endpoints can soundly serve a
+ * subscription route (`outbound-api-server`, design D2 + review M1/m1).
+ *
+ * The subscription-id catalog mirrors `SubscriptionProviderRegistry`'s ids; the
+ * static fast-path is backstopped at runtime by a live registry lookup (see
+ * `isSubscriptionProviderId`) so it degrades gracefully if it drifts. Both
+ * `routeResolver` and `apiServerHandlers` import from here — no duplicated set.
+ *
+ * @module outbound-api/subscriptionSupport
+ */
+
+/**
+ * The registry-aligned subscription provider ids — the outbound layer's SSOT
+ * fast-path. NOTE: `SubscriptionProviderId` is currently a `z.string()` alias,
+ * so this `readonly SubscriptionProviderId[]` typing does NOT compile-enforce
+ * alignment with the registry; drift is instead tolerated at runtime by
+ * `isSubscriptionProviderId`'s live `registry.getProfile` fallback.
+ */
+declare const SUBSCRIPTION_PROVIDER_IDS: readonly SubscriptionProviderId[];
+/**
+ * True when a provider id refers to a subscription-backed provider. Checks the
+ * registry-aligned static catalog first, then falls back to a live registry
+ * lookup (so a registry addition is honored even before this list is updated).
+ *
+ * NOTE (review m2): this classifies by id string. The resolver MUST confirm the
+ * id does not resolve to a real BYO provider row before treating it as
+ * subscription-backed — see `routeResolver` (BYO rows win).
+ */
+declare function isSubscriptionProviderId(providerId: string): boolean;
+/** True when the endpoint's ingress can soundly serve a subscription route. */
+declare function endpointSupportsSubscription(endpoint: OutboundEndpoint): boolean;
+
+/**
+ * routeResolver — turn an endpoint's `EndpointRoutingConfig` + the detected
+ * request role into a `RouteContext` for the shared `provider-proxy` dispatch
+ * (`outbound-api-server`, design D2).
+ *
+ * Steps:
+ *  1. Pick the model for the role (vision → default fallback when `visionModel`
+ *     is unset; vision is optional).
+ *  2. Parse the chosen `"providerId,modelId"` ref.
+ *  3. Gate by `useSubscription`: OFF → only BYO-key providers are eligible
+ *     (subscription-backed providers excluded); ON → subscription-backed
+ *     providers are eligible.
+ *  4. Resolve the provider (BYO via the `ProviderConfigSource`; subscription via the
+ *     subscription registry) and build the `RouteContext` exactly as the
+ *     internal callers do.
+ *  5. Return a clear `503`-style error when the role's required model is unset,
+ *     the provider is unavailable, or the subscription gate excludes it.
+ *
+ * @module outbound-api/routeResolver
+ */
+
+/** A 503-style resolution failure. */
+interface RouteResolveError {
+    status: number;
+    message: string;
+}
+type RouteResolveResult = {
+    ok: true;
+    route: RouteContext;
+    usedRole: RequestRole;
+} | {
+    ok: false;
+    error: RouteResolveError;
+};
+/** Resolve a route for one authenticated outbound request. */
+declare function resolveRoute(args: {
+    config: EndpointRoutingConfig;
+    role: RequestRole;
+    ingressFormat: IngressFormat;
+    llmConfig: ProviderConfigSource;
+    sessionId?: string | null;
+}): Promise<RouteResolveResult>;
+
+/**
+ * Outbound API server module — barrel + singleton accessor.
+ *
+ * The outbound server is constructed ONCE at app bootstrap (sharing the
+ * resident `ProviderProxy`'s route map + deps) and started only when the
+ * persisted `enabled` setting is true. `getOutboundApiServer(deps)` mirrors
+ * `getProviderProxy()`: the first call constructs the instance from the supplied
+ * deps; later calls return it.
+ *
+ * @module outbound-api/index
+ */
+
+/**
+ * Get (or lazily construct) the outbound API server singleton.
+ *
+ * @param deps Required on the FIRST call (app bootstrap). Ignored afterward.
+ * @param onPortChange Optional persistence hook for the EADDRINUSE fallback.
+ */
+declare function getOutboundApiServer(deps?: OutboundApiDeps, onPortChange?: (port: number) => void): OutboundApiServer;
+/** Reset the singleton (tests / teardown only). */
+declare function __resetOutboundApiServerForTests(): void;
+
+export { type ApiServerSettingsStore, type ApplyConfigInput, DEFAULT_OUTBOUND_PORT, EndpointRoutingConfig, OUTBOUND_API_SERVER_CONFIG_KEY, OutboundApiDeps, OutboundApiKeyCreated, OutboundApiServer, OutboundApiServerConfig, OutboundApiServerStatus, OutboundEndpoint, OutboundFormatUrls, OutboundKeyDb, OutboundRateLimiter, RequestRole, SUBSCRIPTION_PROVIDER_IDS, __resetOutboundApiServerForTests, createNamedKey, defaultServerConfig, detectRequestRole, endpointSupportsSubscription, endpointToIngressFormat, formatUrls, getOutboundApiServer, hashKey, isSubscriptionProviderId, loadServerConfig, mergeServerConfig, normalizeServerConfig, resolveRoute, saveServerConfig, verifyPresentedKey };