/** * The gateway request flow (spec §2). This is the real v0 personal-passthrough * orchestration, wire-agnostic: the router calls it for both `/v1/messages` * (Anthropic) and `/v1/chat/completions` (OpenAI). * * Order (spec §2): * 1. caller-auth (verify the SENTROPIC identity) -> resolve CostContext from * the VERIFIED identity (NEVER the body). * 2. resolve provider/model from the body `model`. * 3. (kill-switch) reject any request that would require a cross-user grant * while `crossUserPoolEnabled` is OFF. * 4. pool.select() -> AccountTransportCoordinator.acquire() over the caller's * PERSONAL pool (sticky binding; no silent rebind). * 5. authResolver.resolve() -> executable SecretAuthMaterial (gateway-owned, * refresh-under-lock). Hooks/logs get the REDACTED descriptor only. * 6. dispatch via llm-mesh (faithful provider-compat passthrough). * 7. SETTLE: recordOutcome + the metering hook (BR-47 wiring is a later lot; * the settle HOOK is always called — success, failure, or mid-stream). * * No-retry-after-stream (spec §2): once bytes have streamed, a mid-stream * provider failure settles with failure/estimated usage and does NOT retry. */ import type { AccountTransportOutcome, NativeUsagePricing } from '@sentropic/llm-mesh'; import type { GatewayConfig } from './config.js'; import type { CostContext } from './ports/cost-context.js'; import type { CallerAuthRequestContext } from './ports/caller-auth.js'; import type { ResponsesLimits } from './responses-egress.js'; import type { GatewayDispatchStreamEvent, GatewayWire, ProviderResponseHeaders } from './ports/dispatch.js'; import type { CheckedGatewayBody } from './request-body-retention.js'; import { type RedactedSelectionView } from './redaction.js'; import type { GuardPort } from './ports/guards.js'; import { type GuardedTurnCaptureRecord } from './guards/sse-guard-tee.js'; import type { ReceiptIntegrity } from './ports/gateway-state.js'; import type { RouteFlowDeps } from './route-flow-core.js'; export interface LegacyRefusalReceiptRecord { readonly requestId: string; readonly wire: GatewayWire; readonly model: string; readonly integrity?: ReceiptIntegrity; readonly reason: string; readonly createdAt: string; } /** * Normalized usage the settle hook records. `estimated` is true when the * provider did not report usage (spec §5 never-zero -> estimate). */ export interface SettleUsage extends NativeUsagePricing { readonly inputTokens: number; readonly outputTokens: number; readonly estimated: boolean; } /** Settle context passed to the metering hook (BR-47 wiring lands later). */ export interface SettleContext { readonly cost: CostContext; readonly wire: GatewayWire; readonly providerId: string; readonly model: string; readonly outcome: AccountTransportOutcome['status']; readonly usage: SettleUsage; /** Redacted account view — NEVER the executable material (spec §4). */ readonly account: RedactedSelectionView; } /** * Metering settle hook (spec §5). v0 = a HOOK stub; BR-47 ledger wiring is a * later lot. The flow ALWAYS calls this exactly once per request (success, * failure, or mid-stream failure), so the seam is real even before the ledger. */ export interface MeteringSink { settle(context: SettleContext): Promise | void; } /** Provider/model resolution from the body. */ export interface ResolvedTarget { readonly providerId: string; readonly transportProviderId: string; readonly model: string; /** * Optional reasoning effort the resolved alias implies (e.g. a launch alias * `*-xhigh`). Carried on the target so the routing knowledge stays in the * gateway target-map (single source of truth); the dispatch impl applies it. */ readonly effort?: string; } /** * Resolve provider/model + transport for a model string. v0 personal-passthrough * uses a minimal static map; Lot 3+ replaces it with the catalog/pool snapshot. * Unknown models throw an `unknown-model` GatewayError (Lot 1 404); the router * supplies the validated requested model for the wire message. */ export type TargetResolver = (model: string) => ResolvedTarget | undefined; export interface GatewayFlowDeps { readonly config: GatewayConfig; readonly resolveTarget: TargetResolver; readonly metering: MeteringSink; /** Estimate usage when the provider reports none (spec §5 never-zero). */ readonly estimateUsage?: (wire: GatewayWire, body: unknown) => SettleUsage; readonly guard?: GuardPort; readonly captureEnabled?: boolean; readonly onCapture?: (record: GuardedTurnCaptureRecord) => Promise | void; readonly requestAudit?: RouteFlowDeps['requestAudit']; readonly onRefusalReceipt?: (receipt: LegacyRefusalReceiptRecord) => Promise | void; } /** Inputs the router hands the flow per request. */ export interface GatewayFlowRequest { /** Set only after durable admission by the gateway audit port. */ receiptId?: string; /** Internal guard so a refusal receipt is recorded at most once per request. */ receiptRefused?: boolean; /** Router-owned reference/lease lifecycle; trusted pre-parsers share this owner. */ readonly bodyLease?: CheckedGatewayBody; readonly authContext: CallerAuthRequestContext; readonly wire: GatewayWire; readonly headers: Readonly>; readonly body: unknown; readonly model: string; readonly stream: boolean; readonly signal?: AbortSignal; /** * Router-resolved Responses bounds (spec §16.7). Present only on the * Responses wire; codecs fall back to the spec defaults when absent. */ readonly responsesLimits?: ResponsesLimits; } /** Result of a non-stream gateway call (router sends `body` with `status` + allowlisted headers). */ export interface GatewayJsonResult { readonly status: number; readonly body: unknown; /** Gateway-resolved provider and model that received the request. */ readonly servedTarget: ResolvedTarget; /** Provider response headers (#4); the router forwards the allowlist. */ readonly headers?: ProviderResponseHeaders; } /** * Run a NON-STREAM gateway request end to end. Throws a `GatewayError` on any * pre-dispatch failure (router maps it to a provider-shaped error). On a * provider error response it still settles (failure usage), never leaking pool * internals. */ export declare const runJsonFlow: (deps: GatewayFlowDeps, request: GatewayFlowRequest) => Promise; /** * The result of starting a streaming gateway request: the provider stream * headers (#4, known before the first byte) + the frame generator. The generator * settles exactly once at end. A failure BEFORE the first byte does NOT reach * here — `runStreamFlow` rejects with a provider-shaped `GatewayError` instead * (#6), so the router can return a real HTTP error, never an empty 200. */ export interface GatewayNativeStreamBytes { readonly bytes: Uint8Array; } export interface GatewayStreamResult { readonly relay?: 'native'; readonly headers?: ProviderResponseHeaders; /** Gateway-resolved provider and model that received the request. */ readonly servedTarget: ResolvedTarget; readonly stream: AsyncGenerator; } export declare const runStreamFlow: (deps: GatewayFlowDeps, request: GatewayFlowRequest) => Promise; //# sourceMappingURL=flow.d.ts.map