createHttpAgentReceiver()

@pai/express uses this receiver to map Web Request objects to PAI runtime operations. Mount an app with createPaiExpressReceiver(); the lower-level receiver borrows an existing runtime and leaves its lifecycle with the caller.

import { createHttpAgentReceiver } from "@pai/receiver-http";

const receiver = createHttpAgentReceiver({
  runtime,
  resolveIdentity: async ({ request }) => ({
    identity: { userId: "…", workspaceId: "…" },
  }),
});

Import

import { createHttpAgentReceiver } from "@pai/receiver-http";

Signature

function createHttpAgentReceiver<
  TContract extends AgentContract = AgentContract,
  THostContext = undefined,
>(
  options: CreateHttpAgentReceiverOptions<TContract, THostContext>,
): HttpAgentReceiver<THostContext>;

Parameters

options: CreateHttpAgentReceiverOptions

runtime: AgentRuntime

Existing runtime. The receiver borrows its transport access; the caller closes the runtime.

resolveIdentity: ResolveHttpAgentRequest<TContract, THostContext>

Trusted identity for each request. Receives the operation, request, params, query, optional parsed body, and resolved host context.

telemetry?: PaiTelemetryProvider | false

Defaults to the runtime's telemetry provider. Incoming trace headers are propagated to runtime work.

httpTelemetry?: HttpAgentTelemetryOptions

Enable HTTP spans with true, disable with false, or select operations with { enabled, operations }. Defaults to disabled.

requestLimits?: HttpAgentRequestLimits

Byte limits for decoding request bodies; see Request limits.

deriveFileUrlFallback?: boolean

Derive a URL for GET /files/:fileId when the provider cannot mint one. Defaults to false. The URL is relative to the lookup response; @pai/client-http resolves it against the API address. Use this for same-origin or cookie-authenticated file requests; browser elements cannot add custom authorization headers.

keepAliveMs?: number

Idle SSE keep-alive interval. 0 disables keep-alives.

mapHttpError?: HttpAgentErrorMapper

Return safe { code, message } details or undefined for PAI's fallback.

onHttpError?: false | HttpAgentErrorHandler

Trusted request/stream failure reporter. Omit to inherit the logger or default reporter; false suppresses reporting and diagnostic references.

logger?: PaiLogger | false

Defaults to the runtime's logger. See Errors.

logLevel?: "debug" | "info" | "warn" | "error"

Request limits

Each limit accepts a byte count or false to disable it:

Field	Default	Applies to
`jsonBodyBytes`	1 MiB	JSON request bodies
`multipartBodyBytes`	64 MiB	Complete multipart bodies
`uploadFileBytes`	64 MiB	Uploaded file bytes
`uploadMetadataBytes`	64 KiB	Each multipart text field

Returns

A HttpAgentReceiver<THostContext>.

A routes table. Every route has a method, path, required operation, and handle(context): Promise<Response>.

HttpAgentRouteContext<THostContext> contains request, params, and a getContext getter. The getter may return a value or promise and is required when THostContext is not undefined. JSON routes validate their body before calling the getter and resolving identity; upload routes resolve identity before parsing multipart. The resolved value is passed as context to resolveIdentity.

The receiver has no separate shutdown lifecycle. Close the app or runtime that created it.