Server transport API

Open in

The server transport publishes to an Ably channel, manages the turn lifecycle, and routes cancel signals from clients to active turns. It is the server-side counterpart to the client transport.

Import from the core entry point:

JavaScript

import { createServerTransport } from '@ably/ai-transport'

Or use the Vercel entry point which pre-binds the codec.

createServerTransport

Factory function that creates a ServerTransport instance.

JavaScript

function createServerTransport(options: ServerTransportOptions): ServerTransport

ServerTransportOptions

Property	Required	Type	Description
channel	required	`Ably.RealtimeChannel`	The Ably channel for the session.
codec	required	`Codec<TEvent, TMessage>`	Codec for encoding and decoding messages. See Codec API.
logger	optional	`Logger`	Logger instance for debug output.
onError	optional	`(error: ErrorInfo) => void`	Callback for transport-level errors.

ServerTransport

The ServerTransport object returned by the factory.

newTurn

Create a new turn. Returns a Turn object for managing the turn lifecycle.

JavaScript

function newTurn(options: NewTurnOptions): Turn

close

Close the transport and release resources.

JavaScript

function close(): void

NewTurnOptions

Property	Required	Type	Description
turnId	required	`string`	Unique identifier for this turn.
clientId	optional	`string`	The client that initiated this turn. Used for scoping cancel signals.
parent	optional	`string \| null`	The ID of the parent node in the conversation tree. Used for branching.
forkOf	optional	`string`	The ID of the node this turn forks from, for edit and regenerate operations.
onCancel	optional	`(request: CancelRequest) => Promise<boolean>`	Callback fired when a cancel signal matches this turn. Return `true` to allow cancellation, `false` to reject it. If not provided, all cancels are accepted.
onAbort	optional	`(write: (event: TEvent) => Promise<void>) => void \| Promise<void>`	Callback fired when the turn is aborted. Receives a `write` function to publish final events before the abort finalizes.
onMessage	optional	`(message: Ably.Message) => void`	Hook called before each Ably message is published in this turn. Mutate the message in place to add custom headers.
onError	optional	`(error: ErrorInfo) => void`	Callback for errors during this turn.

Turn

A Turn object manages the lifecycle of a single turn on the server.

start

Announce the start of the turn on the channel. Call this before publishing any messages.

JavaScript

function start(): Promise<void>

addMessages

Publish messages to the channel. Use this to publish user messages or any discrete messages that are not part of a stream.

JavaScript

function addMessages(messages: MessageNode<TMessage>[], options?: { clientId?: string }): Promise<AddMessagesResult>

streamResponse

Pipe a ReadableStream of events through the codec and publish them to the channel. Returns when the stream completes, with a reason indicating how it ended.

JavaScript

function streamResponse(stream: ReadableStream<TEvent>, options?: StreamResponseOptions): Promise<{ reason: TurnEndReason }>

The stream is piped through the codec's encoder, which converts events into Ably publish operations. If the turn is cancelled while streaming, the stream is aborted and the returned reason is 'cancelled'.

addEvents

Publish a batch of events to the channel without streaming. Useful for publishing pre-computed events or events from a non-streaming source.

JavaScript

function addEvents(nodes: EventsNode<TEvent>[]): Promise<void>

end

End the turn with the given reason. Publishes a turn-end marker to the channel.

JavaScript

function end(reason: TurnEndReason): Promise<void>

abortSignal

An AbortSignal that fires when the turn is cancelled. Pass this to your LLM call to stop generation when a cancel signal is received.

JavaScript

const result = await streamText({
  model: openai('gpt-4o'),
  messages,
  abortSignal: turn.abortSignal,
})

CancelRequest

The object passed to the onCancel callback when a cancel signal matches a turn.

Property	Type	Description
message	`Ably.InboundMessage`	The raw Ably message that carried the cancel signal.
filter	`CancelFilter`	The parsed cancel scope from the message headers.
matchedTurnIds	`string[]`	The active turn IDs that would be cancelled if allowed.
turnOwners	`Map<string, string>`	Map of turn ID to the owner's client ID for the matched turns.

CancelFilter

Property	Type	Description
own	`true`	Cancel all turns started by the requesting client.
turnId	`string`	Cancel a specific turn by ID.
clientId	`string`	Cancel all turns by a specific client.
all	`true`	Cancel all active turns on the channel.

Only one property should be set per filter. If no filter is provided, the default is { own: true }.

TurnEndReason

JavaScript

type TurnEndReason = 'complete' | 'cancelled' | 'error'

Value	Description
`'complete'`	The turn finished normally.
`'cancelled'`	The turn was cancelled by a client signal.
`'error'`	The turn ended due to an error.