@pai/receiver-http

Package: @pai/receiver-http

createHttpAgentReceiver() builds the framework-neutral route table mounted by @pai/hono, @pai/express, or a custom Web Request adapter.

Error Mapping

type HttpAgentErrorMappingContext =
  | {
      phase: "request";
      operation: HttpAgentOperation;
      agentName: string;
      agentVersion?: string;
      status: number;
      threadId?: string;
      runId?: string;
    }
  | {
      phase: "stream";
      operation: HttpAgentOperation;
      agentName: string;
      agentVersion?: string;
      threadId?: string;
      runId?: string;
    };

type HttpAgentErrorMapper = (
  error: unknown,
  context: HttpAgentErrorMappingContext,
) => PaiErrorDetails | undefined;

mapHttpError classifies unexpected receiver failures into deliberate client-safe details. Return undefined to use PAI's generic fallback. Mapper failures and invalid returns are isolated and also use the safe fallback.

The mapping context deliberately excludes request bodies, headers, identity, prompts, client data, and tool payloads.

HTTP Error Reporting

type HttpAgentErrorEvent = HttpAgentErrorMappingContext & {
  error: unknown;
  errorId: string;
  publicError: PersistedErrorRecord & { errorId: string };
};

type HttpAgentErrorHandler = (
  event: HttpAgentErrorEvent,
) => void | Promise<void>;

error is the original trusted-server exception. publicError is the safe record sent through HTTP or SSE and carries the same errorId.

CreateHttpAgentReceiverOptions accepts:

{
  mapHttpError?: HttpAgentErrorMapper;
  onHttpError?: false | HttpAgentErrorHandler;
}

Omit onHttpError for PAI's default server console reporter, provide a function to replace it, or pass false to suppress reporting. When reporting is suppressed and no trusted diagnostic is emitted, the safe client error does not receive a diagnostic reference.

Reporter failures are ignored. They cannot change the safe response or stream closure.

Expected validation and portable domain errors retain their normal public responses and are not reported as unexpected receiver failures.

Safe Error Wire Format

Unexpected request failures use a versioned JSON body:

{
  "paiErrorVersion": 1,
  "code": "internal_server_error",
  "message": "Something went wrong. Please try again.",
  "errorId": "PAI-..."
}

After an SSE response has started, the same DTO is sent in an error event:

event: error
data: {"paiErrorVersion":1,"code":"internal_stream_error","message":"The live connection was interrupted. Please try again.","errorId":"PAI-..."}

The version is a format discriminator, not proof of origin or authorization. Clients ignore diagnostic metadata from unknown versions and use their generic safe fallback. Successful SSE events keep their existing unmarked shape.

See Error Handling and HTTP And SSE.