@urun-sh/openai 0.2.60 → 0.3.1

package/dist/hosted/index.d.cts

@@ -0,0 +1,621 @@
+import { Server } from 'node:http';
+import { createClientToken } from '@urun-sh/core';
+import { U as UrunResponses } from '../ResponsesClient-Dft3bg3b.cjs';
+import { b as UrunSessionLike } from '../types-lsVTbNcH.cjs';
+import { P as ProxyClients } from '../server-BfME37pQ.cjs';
+import '../video-out-D20UuJ8G.cjs';
+
+/**
+ * Per-model → per-app routing for the compat proxy (owner directive
+ * 2026-08-07): swapping the model in a coding harness routes the request to
+ * the org's DEPLOYED app for that model. v1 is deployed-only — a uRun model
+ * that is not deployed gets a loud 404 naming `urun serve <id>`; a later
+ * phase (explicitly out of scope here; urun-infra#1490 shared-endpoints)
+ * auto-creates from the model catalog on first request.
+ *
+ * MODEL-ID SURFACE (the documented mapping): a model may be named by
+ *   - the app slug itself        ("qwen3-6-27b-bf16"), or
+ *   - the catalog id             ("qwen3.6-27b"), or
+ *   - the catalog id:variant     ("qwen3.6-27b:bf16"),
+ * where slugification mirrors urun-cli `serve.py _default_app_name` exactly:
+ * lowercase, every non-alphanumeric-non-dash character becomes "-", leading/
+ * trailing dashes stripped (catalog id "qwen3.6-27b" + variant "bf16" → app
+ * "qwen3-6-27b-bf16"). COLLISION RULE: an exact slug match always wins over
+ * the catalog-id (prefix) interpretation.
+ *
+ * RESOLUTION ORDER (one canonical path, documented end to end):
+ *   1. model absent / "urun" / an alias of the startup app  → DEFAULT app.
+ *   2. exact slug match on a deployed serve app             → that app.
+ *   3. catalog-id form matching exactly one deployed app    → that app
+ *      (two or more candidates → loud ambiguity error naming them).
+ *   4. the name maps to an org app that is NOT an active app exposing the
+ *      proxy's serve function                               → loud 404
+ *      naming `urun serve <model>` and the available models.
+ *   5. the name matches a catalog row but no deployed app   → loud 404
+ *      naming `urun serve <id>` (deployed-only v1).
+ *   6. anything else — a model name outside the uRun namespace entirely
+ *      (e.g. the harness's own upstream default, "claude-*"/"gpt-*") →
+ *      DEFAULT app. This IS today's single-app contract, kept deliberately
+ *      so `urun compat <agent>` with the agent's stock model keeps working
+ *      with zero new env; the per-model /stats table records every such
+ *      mapping so it is visible, never silent. Models the proxy ADVERTISES
+ *      on /v1/models can never land here — they resolve (2/3) or fail loud
+ *      (4/5) above.
+ *
+ * NO-DEFAULT MODE (`defaultApp: null`) — the HOSTED multi-tenant lane
+ * (`src/hosted/`): a shared endpoint serving every org has no "the app this
+ * proxy was started for", so rules 1 and 6 have nothing to fall back TO.
+ * Rather than inventing one (picking "some" app for a caller would be the
+ * worst kind of silent divergence), both rules become the SAME loud
+ * {@link UnknownModelError} that rules 4/5 already raise: name a deployed
+ * model, here is the list. Rules 2–5 are byte-for-byte the local behavior —
+ * one router, one resolution order, two configurations.
+ */
+/** One org app row from `GET {orgApi}/apps` (urun-cli `ApiClient.list_apps`). */
+interface DeployedApp {
+    app_slug: string;
+    function_name?: string | null;
+    deployment_status?: string | null;
+    [k: string]: unknown;
+}
+/**
+ * A session handle names a pooled session that no longer exists (closed,
+ * evicted after its pod died, replaced by a re-home, or the proxy restarted).
+ * The caller asked to REATTACH that exact session — opening a fresh one and
+ * calling it "resumed" would be a silent lie, so this is always loud.
+ */
+declare class SessionGoneError extends Error {
+}
+/** OpenAI-shaped model list (same shape as models.ts listModels). */
+interface RouterModelList {
+    object: 'list';
+    data: Array<{
+        id: string;
+        object: 'model';
+        created: number;
+        owned_by: string;
+    }>;
+}
+interface ModelRouterOptions<S> {
+    /**
+     * The startup app slug (URUN_APP) — the DEFAULT model — or `null` for the
+     * hosted multi-tenant lane, which has no per-proxy default app: there,
+     * every request must NAME a deployed model and an unnamed/unknown one
+     * fails loud instead of silently landing somewhere (see the module header,
+     * "NO-DEFAULT MODE").
+     */
+    defaultApp: string | null;
+    /** The serve function name every routed app must expose (URUN_FUNCTION). */
+    fnName: string;
+    /** Open a backhaul session for an app slug (called at most once per app). */
+    openSession: (appSlug: string) => S | Promise<S>;
+    /** Terminal release for one pool entry (Session.end() underneath). */
+    closeSession: (entry: S) => Promise<void>;
+    /**
+     * List the org's deployed apps, or null when the credentials cannot
+     * (URUN_JWT lane: the pre-vended token is scoped to the default app, so
+     * there is no org listing AND no cross-app session — routing degrades to
+     * the default-app-only contract, which is exactly today's behavior).
+     */
+    listApps: (() => Promise<DeployedApp[]>) | null;
+    /**
+     * Catalog rows (models.ts fetchCatalogRows) as the uRun-namespace oracle
+     * for rule 5, or null when catalog access is not configured.
+     */
+    listCatalog: (() => Promise<Array<{
+        model_id: string;
+        variant: string;
+    }>>) | null;
+    /** Deployed-apps cache TTL (the list changes on deploys, not per request). */
+    appsTtlMs?: number;
+    /**
+     * The stable NATIVE identity of one pooled entry (the uRun session id in
+     * the proxy wiring — the same identity the serve-side session-affinity tag
+     * rides, urun-python#1556). Powers the session-identity seam
+     * ({@link ModelRouter.handleFor} / {@link ModelRouter.sessionForHandle});
+     * a router without it fails LOUD on those calls, never approximates.
+     */
+    sessionKey?: (entry: S) => string;
+}
+/**
+ * The session pool: one backhaul session per deployed app, keyed by app slug,
+ * opened lazily on the first request that routes to it and reused for every
+ * subsequent one. The startup app is seeded eagerly by the CLI. Sessions
+ * close on proxy shutdown via {@link closeAll}; there is NO idle-close policy
+ * (deliberate v1 simplification — noted as a follow-up in the PR).
+ */
+declare class ModelRouter<S> {
+    private readonly opts;
+    private readonly pool;
+    private appsCache;
+    constructor(opts: ModelRouterOptions<S>);
+    /** Seed an already-open session (the CLI's eagerly-opened startup app). */
+    seed(appSlug: string, entry: S): void;
+    private deployedApps;
+    /** Apps this proxy may serve: active AND exposing the serve function. */
+    private servable;
+    private availableIds;
+    /**
+     * NO-DEFAULT MODE's terminal for rules 1 and 6: there is no app to fall
+     * back to, so say so loudly and list what the CALLER'S org actually has.
+     * Never returns.
+     */
+    private noDefaultApp;
+    /**
+     * Resolve a request's `model` to an app slug — the documented resolution
+     * order from the module header. Throws {@link UnknownModelError} for a uRun
+     * model that is not deployed (rules 4/5).
+     */
+    resolveApp(model: string | undefined): Promise<string>;
+    /** The pooled session for a model — opened lazily, reused afterwards. */
+    sessionFor(model: string | undefined): Promise<{
+        app: string;
+        entry: S;
+    }>;
+    private keyOf;
+    /**
+     * SESSION-IDENTITY SEAM (a): the opaque stable handle for the pooled
+     * session currently serving `model`'s turns. Rides the SAME acquisition
+     * path as every request ({@link sessionFor}) — the session opens lazily if
+     * this model has none yet — and derives the handle from native identity
+     * (app slug + uRun session id), zero bespoke bookkeeping.
+     */
+    handleFor(model: string | undefined): Promise<{
+        app: string;
+        handle: string;
+    }>;
+    /**
+     * SESSION-IDENTITY SEAM (b): the exact pooled session a handle names.
+     * NEVER opens a fresh session — a handle whose session is gone (closed,
+     * evicted, re-homed to a replacement, proxy restarted) or malformed throws
+     * {@link SessionGoneError} loudly. Resume is reattach-or-fail, not
+     * reattach-or-quietly-restart.
+     */
+    sessionForHandle(handle: string): Promise<{
+        app: string;
+        entry: S;
+    }>;
+    /**
+     * Drop ONE pooled session whose backhaul died (its pod was restarted /
+     * drained / deleted) and release it — the next {@link sessionFor} opens a
+     * fresh one, i.e. asks the control plane for a new assignment. Used by the
+     * one-shot re-home (rehome.ts, urun-sh/urun-python#1592).
+     *
+     * IDENTITY-GUARDED (the same rule the pi lane's SessionPool follows): a
+     * concurrent request that already re-homed this app has put a NEWER entry
+     * under the key, and evicting that would close a healthy session out from
+     * under it.
+     */
+    evict(app: string, entry: S): Promise<void>;
+    /**
+     * `GET /v1/models`: the org's deployed serve apps as model entries, the
+     * default app FIRST. On the JWT lane (no org listing) this is the default
+     * app plus any app already in the pool — the gap is called out loudly in
+     * the PR, not papered over here.
+     */
+    modelList(): Promise<RouterModelList>;
+    /** Close every pooled session (Session.end() underneath) — proxy shutdown. */
+    closeAll(): Promise<void>;
+}
+
+/**
+ * HOSTED AUTH — the Bearer key IS the identity AND the tenancy.
+ *
+ * Owner directive (2026-08-19): "the Bearer key alone determines the org —
+ * resolve org_id from the key server-side and scope ALL routing to THAT org.
+ * No org id in the URL or headers." So this module has exactly one job:
+ * `Authorization: Bearer <urun org api key>` → `org_id`, or a loud 401.
+ *
+ * IT INVENTS NO AUTH SCHEME. It calls the platform's OWN key verification —
+ * `createClientToken(apiKey)` from `@urun-sh/core`, i.e.
+ * `POST {gateway}/api/client-tokens` with the key on `Authorization` — which
+ * is the same call `urun compat` already makes to open a session, and which
+ * returns `org_id`: the key's org binding, straight from the control plane.
+ * There is no JWT path, no org header, no locally-held mapping table.
+ *
+ * NO STANDING CREDENTIAL. This process holds no platform secret at all: every
+ * upstream call it makes rides the CALLER'S OWN key. That is what makes an
+ * internet-facing shared endpoint safe to run, and it is what makes cross-org
+ * isolation structural rather than a rule this code has to remember — a key
+ * simply cannot mint a token, list apps, or dial a session outside its org.
+ */
+
+/**
+ * A refused request. `status` is what the caller sees; the message is the
+ * OpenAI-envelope `error.message`. Every rejection here is explicit — there
+ * is no anonymous lane to fall through to.
+ */
+declare class ProxyAuthError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+/** The control plane could not be reached/asked. Loud 502, never a pass. */
+declare class ControlPlaneUnavailableError extends Error {
+    constructor(message: string);
+}
+/** The verified caller: their key, and the org the control plane bound it to. */
+interface CallerIdentity {
+    apiKey: string;
+    orgId: string;
+}
+/**
+ * Pull the raw key off `Authorization: Bearer <key>`. Missing, malformed, or
+ * a non-Bearer scheme is a 401 — never an anonymous request.
+ */
+declare function bearerFrom(headerValue: string | undefined): string;
+/**
+ * How long a verified key→org binding is reused before re-asking the control
+ * plane. Bounded and short: a revoked key stops working within this window,
+ * and until then it can still only reach its OWN org (the binding is the org
+ * it always had), so the window can never widen a tenancy boundary.
+ */
+declare const ORG_BINDING_TTL_MS = 60000;
+/** The most distinct keys one replica remembers verifying (bounded memory). */
+declare const MAX_CACHED_KEYS = 4096;
+interface OrgResolverOptions {
+    /** The session-gateway base the mint call goes to (external input). */
+    gatewayUrl: string;
+    /** Injected in tests; production uses the SDK's own fetch. */
+    mint?: typeof createClientToken;
+    /** Injected in tests so cache expiry is exercised without wall-clock waits. */
+    now?: () => number;
+}
+/**
+ * Key → org resolution with a short bounded cache.
+ *
+ * The cache is keyed on the RAW key held only in memory for the TTL. It is
+ * deliberately not a "session registry": it holds no session, no doc, no
+ * routing state — nothing that would have to be shared between replicas, and
+ * nothing whose loss changes behavior (a cold replica just re-verifies).
+ */
+declare class OrgResolver {
+    private readonly opts;
+    private readonly cache;
+    private readonly mint;
+    private readonly now;
+    constructor(opts: OrgResolverOptions);
+    /**
+     * Verify a Bearer key against the control plane and return its org binding.
+     *
+     * Three outcomes, all explicit:
+     *   - the control plane binds the key to an org  → {@link CallerIdentity};
+     *   - the control plane rejects the key (401/403) → {@link ProxyAuthError};
+     *   - the control plane cannot be asked           → loud
+     *     {@link ControlPlaneUnavailableError} (502). NEVER a pass: a proxy that
+     *     admitted requests while it could not verify keys would be an open
+     *     relay into every org.
+     */
+    resolve(apiKey: string): Promise<CallerIdentity>;
+    /** Test/ops seam: forget every cached binding. */
+    clear(): void;
+}
+
+/**
+ * SESSION GONE for the proxy serve lane — level-triggered, keyed off the
+ * transport's OWN close/rejection signals (live defect, prod-usw2 2026-08-12).
+ *
+ * A pooled backhaul session can be closed by the PLATFORM out from under the
+ * proxy (close_reason=idle_timeout, or a serve-side crash close). The request
+ * marker is a write into the session's `llm` Yjs doc — and a Yjs provider
+ * whose room is gone buffers the write locally and redials FOREVER (that is
+ * its contract: "Still retrying — the doc provider never gives up"), so every
+ * request dispatched into a dead session was silently swallowed: zero events,
+ * no error, no re-home (live receipt: session
+ * ef1bf00c-24d7-4327-b057-452a72221e43 idle-closed 18:50:55Z; a /v1/messages
+ * request accepted 18:51:18Z produced nothing for 147s until the client gave
+ * up).
+ *
+ * This module derives ONE latched "session gone" verdict from the two native
+ * lifecycle surfaces core already exposes — NO liveness timers, NO
+ * heartbeats, no polling (the pi lane's stall watchdog stays a pi-lane
+ * concern):
+ *
+ *   1. The doc provider's own connection-state surface
+ *      (yjs-provider `DocConnectionState`, via `SessionDocument.
+ *      onConnectionState` on the SAME `llm` doc the transport writes request
+ *      markers into): `consecutiveFailures` at/above the provider's own
+ *      outage bar (`DOC_OUTAGE_LOUD_THRESHOLD` = 3 — the exact state the live
+ *      log line reports, close code 1002 / an upgrade rejection for a room
+ *      that no longer exists) means the session's backhaul is unreachable.
+ *      `consecutiveFailures` resets on every healthy sync, so a recovered
+ *      blip never trips this.
+ *
+ *   2. Core Session's own terminal phase machinery (`Session.onPhase` →
+ *      'ended' / 'expired' / 'error') — the session lease the pool already
+ *      tracks (the same signal cli.ts `onSessionEnd` rides).
+ *
+ * Consumers (cli.ts):
+ *   - {@link watchSessionGone} per pooled entry; `onGone` → `router.evict`
+ *     (level-triggered eviction, so the NEXT acquire re-allocates through the
+ *     existing `sessionFor` path);
+ *   - {@link guardSessionGone} around each dispatched event stream, so an
+ *     in-flight (or newly dispatched) request THROWS {@link SessionGoneError}
+ *     promptly instead of waiting on a doc room that will never answer. The
+ *     throw surfaces BEFORE any content event, which is exactly what the
+ *     existing one-shot re-home (rehome.ts) turns into a fresh-session
+ *     re-dial — no parallel retry mechanism.
+ */
+
+/** A latched per-entry session-gone verdict. */
+interface SessionGoneWatch {
+    /** The latched verdict — null while the session is (believed) alive. */
+    gone(): SessionGoneError | null;
+    /**
+     * Subscribe to the gone transition. Level-triggered: an already-gone watch
+     * invokes the callback immediately. Fires at most once per subscriber.
+     * Returns an unsubscribe fn.
+     */
+    onGone(cb: (err: SessionGoneError) => void): () => void;
+    /** Detach from the session's surfaces (entry teardown / proxy shutdown). */
+    dispose(): void;
+}
+
+/**
+ * THE canonical backhaul factory — the one place a `ProxyClients` seam is
+ * built over uRun sessions.
+ *
+ * This code used to live inside `cli.ts`, which executes `main()` on import
+ * and therefore cannot be imported by anything (tests included). Hosting the
+ * SAME proxy as a server (`src/hosted/`) needs exactly this wiring, so it was
+ * lifted here verbatim rather than forked: `cli.ts` (local, single-tenant) and
+ * `hosted/` (shared, multi-tenant) now call the identical
+ * {@link buildRouter} / {@link buildClients} pair, and the only difference
+ * between them is the {@link BackhaulConfig} they hand it.
+ *
+ * The two configurations:
+ *   - LOCAL   `defaultApp: <URUN_APP>` — the startup app is the default model
+ *             and is seeded eagerly, exactly as `urun compat` always behaved.
+ *   - HOSTED  `defaultApp: null`       — no default model, nothing seeded;
+ *             every request must name a deployed model (routing.ts,
+ *             "NO-DEFAULT MODE") and `auth.apiKey` is the CALLER'S OWN org
+ *             API key, so every control-plane call and every session dial is
+ *             org-scoped by the platform itself.
+ */
+
+/**
+ * The `model_catalog` oracle (models.ts) behind routing rule 5 — telling an
+ * UNDEPLOYED uRun catalog model apart from a name outside the uRun namespace.
+ * `null` disables rule 5; every caller says so out loud when it does.
+ */
+interface CatalogConfig {
+    catalogUrl: string;
+    anonKey: string;
+}
+/**
+ * The session plus the SDK's OWN terminal release (`Session.end()`), and the
+ * core Session surfaces the identity seam rides — all NATIVE @urun-sh/core
+ * Session members (`id`, `endsAt`, `onPhase`), typed optional here because
+ * the narrow UrunSessionLike does not declare them; the seam fails LOUD when
+ * a session object lacks them (no approximation, no minted identity).
+ */
+type OwnedSession = UrunSessionLike & {
+    end: () => Promise<unknown>;
+    id?: string;
+    endsAt?: Date | null;
+    onPhase?: (handler: (phase: {
+        name: string;
+    }) => void) => () => void;
+};
+/**
+ * One pooled backhaul: the session, its (stateful) Responses client, and the
+ * latched session-gone watch over the session's own transport signals.
+ */
+type PoolEntry = {
+    session: OwnedSession;
+    responses: UrunResponses;
+    gone: SessionGoneWatch;
+};
+
+/**
+ * PER-CALLER BACKHAULS — the multi-tenant half of the hosted endpoint.
+ *
+ * One {@link ModelRouter} + {@link ProxyClients} per verified API key, built
+ * by the SAME `buildRouter`/`buildClients` factory the local `urun compat`
+ * proxy uses (proxy/backhaul.ts). Nothing about routing, pooling, re-homing
+ * or session-gone handling is reimplemented here; this module only decides
+ * WHICH backhaul a request gets.
+ *
+ * WHY KEYED ON THE API KEY, NOT THE ORG: two keys in one org must not share a
+ * backhaul, because every session dial and every usage event is attributed to
+ * the key that minted its token (`usage_events.api_key_id`). Sharing would
+ * silently bill one key's traffic to another. Same-org keys therefore get
+ * separate pools — a small duplication that keeps attribution honest.
+ *
+ * CROSS-ORG ISOLATION IS STRUCTURAL, NOT BOOKKEEPING. A tenant's router is
+ * built with the caller's OWN key as its only credential, so:
+ *   - `/v1/models` enumerates `GET {apiUrl}/apps` WITH THAT KEY — the control
+ *     plane returns that org's apps and no others;
+ *   - a session dial mints a client token scoped to `<app>/serve` WITH THAT
+ *     KEY — the control plane refuses to scope it outside the key's org.
+ * There is no place in this process where one org's app list or session could
+ * be handed to another org's key, because this process never holds a
+ * credential that spans orgs.
+ *
+ * HORIZONTAL SCALE (phase 1). There is deliberately NO shared state plane —
+ * no valkey, no shard map, no cross-replica session registry. Two facts make
+ * one unnecessary:
+ *   1. Nothing here is authoritative. A replica's tenant map is a CACHE of
+ *      backhauls it happens to have open; a cold replica rebuilds it from the
+ *      caller's key on the first request. Losing it changes no answer.
+ *   2. Replicas converge on the platform's OWN dedupe rather than on a
+ *      registry of ours: client tokens are minted with a STABLE `subject`
+ *      derived from the key, and the platform dedupes sessions per
+ *      (org, actor, app, function) — so replica A and replica B dialing the
+ *      same (key, app) coalesce onto ONE platform session. That is the
+ *      library's own mechanism doing the sharding.
+ * The yjs/valkey state plane in urun-infra#1490 §7 is therefore NOT built
+ * here, and is not silently missing either — it is unnecessary for this
+ * phase's correctness and is called out as such in the PR.
+ */
+
+/**
+ * The most distinct callers one replica keeps backhauls open for. On overflow
+ * the least-recently-used tenant is closed (`ModelRouter.closeAll()` — the
+ * SDK's own terminal release).
+ *
+ * HONEST TRADEOFF, not a costless one: LRU position is refreshed when a
+ * request STARTS, so a tenant part-way through a long generation can become
+ * least-recently-used and be evicted under its own in-flight stream. That
+ * failure is LOUD, not silent — the existing session-gone machinery turns it
+ * into a terminal error event in the lane's native SSE shape, and the next
+ * request re-dials. Making it impossible needs in-flight refcounting, i.e.
+ * exactly the bespoke bookkeeping this design avoids, so phase 1 sets the cap
+ * high enough that reaching it is itself the signal to revisit.
+ *
+ * There is intentionally no idle TIMER: an idle tenant's pooled sessions are
+ * reaped by the PLATFORM'S own idle-close, and the level-triggered
+ * session-gone watch (proxy/session-gone.ts) evicts each entry from the pool
+ * the moment that happens. So an idle tenant decays to an empty router by
+ * itself, through the platform's mechanism, with no reclaim timers of ours.
+ */
+declare const MAX_TENANTS = 512;
+interface TenantRegistryOptions {
+    /** The session-gateway base sessions are opened against. */
+    baseUrl: string;
+    /** The org control-plane API base (`GET {apiUrl}/apps`). */
+    apiUrl: string;
+    /** The model-catalog oracle for routing rule 5, or null. */
+    catalog: CatalogConfig | null;
+    /** Injected in tests; production builds real uRun backhauls. */
+    build?: (caller: CallerIdentity) => {
+        router: ModelRouter<PoolEntry>;
+        clients: ProxyClients;
+    };
+}
+/**
+ * A stable, non-secret `subject` for one caller's client tokens. Derived from
+ * the key so it is identical on every replica (that is the whole point — see
+ * the module header's HORIZONTAL SCALE note), and hashed so the raw key never
+ * travels inside a token claim or a log line.
+ */
+declare function tenantSubject(apiKey: string): string;
+declare class TenantRegistry {
+    private readonly opts;
+    /** Insertion-ordered = LRU order, because a hit re-inserts at the end. */
+    private readonly tenants;
+    constructor(opts: TenantRegistryOptions);
+    private build;
+    /** The backhaul for THIS caller, opened on first use and reused after. */
+    clientsFor(caller: CallerIdentity): ProxyClients;
+    /** Live tenant count — the readiness/ops view, and the tests' assertion. */
+    get size(): number;
+    /** Shutdown: end every pooled session through `Session.end()`. */
+    closeAll(): Promise<void>;
+}
+
+/**
+ * The hosted endpoint's configuration.
+ *
+ * CONFIG MANDATE (org-wide): env vars are NOT a config mechanism. The ONLY
+ * things read from the environment here are genuine EXTERNAL INPUTS — which
+ * control plane this deployment points at, and the runtime-injected `PORT`.
+ * Everything behavioral is a module constant in this file, visible in one
+ * place and changed by editing code, never by a knob on a running pod.
+ *
+ * There is deliberately NO credential input. The service holds no standing
+ * platform secret: every upstream call rides the CALLER'S own org API key
+ * (see hosted/auth.ts), which is what lets an internet-facing shared endpoint
+ * exist without mounting an org-wide credential onto it.
+ */
+
+/**
+ * The container's listen port. The interface contract with the deployment
+ * chart is 8080; `PORT` is the runtime-injected override (the one env var
+ * class the mandate keeps), never a behavior knob.
+ */
+declare const DEFAULT_PORT = 8080;
+/**
+ * The serve function every routed app must expose. HARDCODED, not an env var:
+ * "which function name is a serve lane" is a platform contract, not a
+ * per-deployment tuning knob, and a pod that could be pointed at a different
+ * function would silently serve a different shape of app.
+ */
+declare const SERVE_FUNCTION = "serve";
+/**
+ * The address the server binds. A hosted pod must accept traffic from the
+ * Service, so this is all interfaces — the opposite of the local CLI proxy's
+ * loopback-only bind, and stated explicitly rather than defaulted into.
+ */
+declare const BIND_HOST = "0.0.0.0";
+/** Validated external inputs for one hosted deployment. */
+interface HostedConfig {
+    /** Listen port (runtime-injected `PORT`, default {@link DEFAULT_PORT}). */
+    port: number;
+    /**
+     * The SESSION-GATEWAY base (`https://api.urun.sh`) — sessions are opened
+     * against it AND the client-token mint (`POST {}/api/client-tokens`), which
+     * is also the key-verification call, lives on it.
+     */
+    baseUrl: string;
+    /** The org control-plane API base (`GET {}/apps`), default `{baseUrl}/v1`. */
+    apiUrl: string;
+    /** The `model_catalog` oracle for routing rule 5, or null when unconfigured. */
+    catalog: CatalogConfig | null;
+}
+/**
+ * Read and VALIDATE the deployment's external inputs. Every failure is loud
+ * at startup: a pod that cannot name its control plane must not come up
+ * half-configured and start answering requests it cannot serve.
+ */
+declare function resolveHostedConfig(env?: NodeJS.ProcessEnv): HostedConfig;
+
+/**
+ * THE HOSTED SHARED ENDPOINT — `inference-proxy`.
+ *
+ * Owner directive (2026-08-19): "stand up a managed endpoint, authenticated
+ * via urun api key, that scales HA, hosts the proxy so that we can just point
+ * at it with api key from the org its deployed in and use just like
+ * openai/gemini." Plus the binding addition: the Bearer key ALONE determines
+ * the org; there is no org id in the URL or in a header.
+ *
+ * This file is the server SHELL only. It contains no OpenAI/Anthropic
+ * protocol code of its own: every `/v1` request is handed to
+ * `createProxyRequestHandler` (proxy/server.ts) — the very same handler the
+ * local `urun compat proxy` mounts — with a per-request `ProxyClients`
+ * resolved from the caller's key. One implementation, two deployments.
+ *
+ * ROUTES (the contract the deployment chart is built against):
+ *   GET  /healthz  liveness  — process is up. No upstream calls, ever.
+ *   GET  /readyz   readiness — ALSO requires the control plane to be
+ *                  reachable, because a replica that cannot verify API keys
+ *                  or list apps can serve nothing and must be pulled out of
+ *                  the Service rather than answering 502s.
+ *   *    /v1/...   the compat surface, org-scoped by the Bearer key.
+ *   *    anything else → 404 in the OpenAI error envelope.
+ *
+ * WHAT IS DELIBERATELY NOT HERE: `/stats`. The local proxy exposes it for the
+ * launcher's reuse probe; on a shared endpoint it would publish one tenant's
+ * per-model traffic to every other caller, so the hosted router simply never
+ * dispatches it.
+ */
+
+/**
+ * How long a readiness verdict is reused. Kubernetes probes every few
+ * seconds; without this the replica would hammer the control plane purely to
+ * answer its own probes. Short enough that a control-plane outage pulls the
+ * pod from the Service within one probe period or two.
+ */
+declare const READINESS_TTL_MS = 5000;
+/** Readiness probes must not hang: an unanswered probe IS a failed probe. */
+declare const READINESS_TIMEOUT_MS = 3000;
+interface HostedProxyOptions extends HostedConfig {
+    /** Injected in tests; production uses the real control-plane probe. */
+    probeControlPlane?: () => Promise<{
+        ready: boolean;
+        detail: string;
+    }>;
+    /** Injected in tests so key verification is exercised without a cluster. */
+    resolver?: OrgResolver;
+    /** Injected in tests so backhauls are stubbed at the seam. */
+    registry?: TenantRegistry;
+}
+/**
+ * Build (not listen) the hosted endpoint. The caller owns listen/close, and
+ * `closeAll` releases every pooled backhaul through `Session.end()`.
+ */
+declare function createHostedProxy(options: HostedProxyOptions): {
+    server: Server;
+    closeAll: () => Promise<void>;
+};
+
+export { BIND_HOST, type CallerIdentity, ControlPlaneUnavailableError, DEFAULT_PORT, type HostedConfig, type HostedProxyOptions, MAX_CACHED_KEYS, MAX_TENANTS, ORG_BINDING_TTL_MS, OrgResolver, type OrgResolverOptions, ProxyAuthError, READINESS_TIMEOUT_MS, READINESS_TTL_MS, SERVE_FUNCTION, TenantRegistry, type TenantRegistryOptions, bearerFrom, createHostedProxy, resolveHostedConfig, tenantSubject };