ClientSession

The ClientSession subscribes to an Ably channel, decodes incoming messages through a codec, and builds a conversation tree. It owns the channel attach and the cancel-publish path, exposes a default branch-aware View for rendering, and lets you derive additional views over the same tree.

Construct one with createClientSession from the core entry point. For Vercel UIMessage sessions, use the pre-bound factory from @ably/ai-transport/vercel instead.

import * as Ably from 'ably';
import { createClientSession } from '@ably/ai-transport';
import { createUIMessageCodec } from '@ably/ai-transport/vercel';

const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });

const session = createClientSession({
  client: ably,
  channelName: 'conversation-42',
  codec: createUIMessageCodec(),
});

await session.connect();

Properties

Create a client session

Construct a ClientSession bound to an Ably channel. The session does not attach to the channel until connect() resolves.

import * as Ably from 'ably';
import { createClientSession } from '@ably/ai-transport';
import { createUIMessageCodec } from '@ably/ai-transport/vercel';

const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });

const session = createClientSession({
  client: ably,
  channelName: 'conversation-42',
  codec: createUIMessageCodec(),
});

Parameters

Returns

ClientSession<TInput, TOutput, TProjection, TMessage>. The session instance. Call connect() to attach before sending or cancelling.

Connect the session

Subscribe to the channel and implicitly attach. Idempotent: subsequent calls return the same promise.

All write methods on view and cancel throw InvalidArgument until connect() resolves.

await session.connect();

Returns

Promise<void>. Resolves when the channel is attached and the session is ready for writes.

Create an additional view

Create an additional view over the same conversation tree. Each view has independent branch selections and pagination state.

The caller owns the returned view's lifecycle: call its close() when it is no longer needed, or session.close() closes it.

const secondaryView = session.createView();
secondaryView.branchSelection(messageId).select(1);

// the default view is unaffected
session.view.branchSelection(messageId).index; // 0

Returns

ClientView<TInput, TMessage>. A new view with its own pagination window and branch selection state.

Cancel a run

Publish a cancel signal for the specified run. The agent receives the cancel through its own channel subscription and ends the run with reason 'cancelled'.

const clientRun = await session.view.send({
  kind: 'user-message',
  message: {
    id: crypto.randomUUID(),
    role: 'user',
    parts: [{ type: 'text', text: 'Tell me a story' }],
  },
});

// later, cancel from the UI.
// clientRun.cancel() works immediately, even before the agent's
// run-start has been observed (so clientRun.runId is still empty).
await clientRun.cancel();

// Or, when you already have a resolved runId (for example from a
// RunInfo in view.runs()):
// await session.cancel(someRunInfo.runId);

Parameters

Returns

Promise<void>. Resolves once the cancel message has been published. The cancel is best-effort: if the agent has already ended the run, the cancel is a no-op.

ClientRun

The handle returned by view.send, regenerate, and edit. It extends the shared BaseRun read-model (runId, status, error, messages) with the client's control methods, including the run-scoped steer verb.

Properties

Steer the run

Publish a codec input event that targets this run. The steering message carries this run's run-id so the agent folds it into the active run rather than starting a new run. Pass the same shape view.send accepts, typically codec.createUserMessage(...). The SDK awaits runId internally, so this is safe to call as soon as the handle is returned. Once an ai-run-end has folded for this run the handle is dead and further steer() calls return immediately-rejected promises.

const { published, outcome } = activeRun.steer(createUIMessageCodec().createUserMessage({
  id: crypto.randomUUID(),
  role: 'user',
  parts: [{ type: 'text', text: 'Also include vegan options.' }],
}));

const { serial } = await published;
const { consumed, runTerminalReason } = await outcome;

Parameters

Returns

SteerResult. Two promises: published for the channel-publish acknowledgement, and outcome for the consumed determination resolved at the run's next terminal event.

Cancel the run

Cancel this specific run. Keyed by inputCodecMessageId, which the client owns synchronously, so a cancel issued before the agent mints the runId is still honoured (the agent buffers it and fires it once its input-event watcher matches the trigger). Resolves once the cancel is published; it does not wait for started.

Build the invocation

Build the Invocation pointer for this run, carrying only inputEventId and the session's channel name. POST run.toInvocation().toJSON() to your agent endpoint to wake the agent; run identity lives on the channel rather than in the invocation body.

Subscribe to session errors

Subscribe to non-fatal session errors. These indicate something went wrong but the session is still operational; examples are subscription callback failures and channel continuity loss.

const unsubscribe = session.on('error', (error) => {
  console.error('Session error:', error.code, error.message);
});

// later, when the listener is no longer needed
unsubscribe();

Parameters

Returns

() => void. An unsubscribe function. Call it to remove the listener.

Close the session

Tear down the session. Unsubscribe from the channel, close active streams, clear handlers, and prevent further operations.

close() is local-state-only. The server keeps streaming until its runs end on their own. To stop in-progress runs, call cancel for each before close().

const runIds = session.view.runs()
  .filter((run) => run.status === 'active')
  .map((run) => run.runId);

await Promise.all(runIds.map((runId) => session.cancel(runId)));
await session.close();

Returns

Promise<void>. Resolves once the channel has been released.

Example

End-to-end usage covering construction, connect, send, and teardown.

import * as Ably from 'ably';
import { createClientSession } from '@ably/ai-transport';
import { createUIMessageCodec } from '@ably/ai-transport/vercel';

const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });

const session = createClientSession({
  client: ably,
  channelName: 'conversation-42',
  codec: createUIMessageCodec(),
});

await session.connect();

session.view.on('update', () => {
  render(session.view.getMessages().map(({ message }) => message));
});

const clientRun = await session.view.send(createUIMessageCodec().createUserMessage({
  id: crypto.randomUUID(),
  role: 'user',
  parts: [{ type: 'text', text: 'Plan a 3-day trip to Lisbon.' }],
}));

// The SDK doesn't POST. The application wakes the agent itself.
await fetch('/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(clientRun.toInvocation().toJSON()),
});

// The agent mints the runId on the server, so clientRun.runId is empty
// until run-start is observed. Await `started`, then read it.
await clientRun.started;
const runId = clientRun.runId;

await session.close();
ably.close();