Skip to content

Amend AIT-ST1/CT1 for client + channelName API #467

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
zknill wants to merge 2 commits into
base: ai-transport-features
Choose a base branch
from
+10 −2
Open

Amend AIT-ST1/CT1 for client + channelName API #467

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f49cf1a
Amend AIT-ST1/CT1 for client + channelName API
zknill May 6, 2026
277f8f8
Rewrite AIT-ST1a/CT1a as a fallback chain
zknill May 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions specifications/ai-transport-features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,11 @@ The agent (server-side) session manages the run lifecycle over an Ably channel.

### Factory

- `(AIT-ST1)` The SDK must provide a `createAgentSession` factory that accepts a channel, codec, optional logger, and optional `onError` callback, and returns an `AgentSession`.
- `(AIT-ST1)` The SDK must provide a `createAgentSession` factory that accepts an `Ably.Realtime` client, a channel name, a codec, an optional logger, and an optional `onError` callback, and returns an `AgentSession`.
- `(AIT-ST1a)` On construction the agent session must configure the supplied Realtime client to attribute usage to this SDK and resolve the channel by name. Configuration must be idempotent — repeated construction with the same client must leave the attribution state unchanged, so multiple sessions sharing one client are safe. The session must not close the client or release the channel on `close()`; the caller owns the client's lifecycle. The session owns its channel — callers must not also resolve the same channel name elsewhere with conflicting channel options. The attribution mechanism follows the fallback chain in `AIT-ST1a1`–`AIT-ST1a3`, modeled on chat spec [CHA-IN1](https://sdk.ably.com/builds/ably/specification/main/chat-features/#CHA-IN1).
- `(AIT-ST1a1)` Where the underlying Realtime SDK exposes a wrapper-SDK proxy mechanism (per [CHA-IN1a](https://sdk.ably.com/builds/ably/specification/main/chat-features/#CHA-IN1a)), the session must use it with `{ agents: { 'ai-transport-js': VERSION } }` and use the proxy for all subsequent channel operations.
- `(AIT-ST1a2)` Where the wrapper-SDK proxy mechanism does not exist (current ably-js), the session must inject `'ai-transport-js' -> VERSION` into the client's `options.agents` map AND pass `{ params: { agent: 'ai-transport-js/<VERSION>' } }` on `client.channels.get(channelName)`. Mirrors [CHA-IN1e](https://sdk.ably.com/builds/ably/specification/main/chat-features/#CHA-IN1e).
- `(AIT-ST1a3)` SDK authors must register the agent identifiers used here in the common repository (`ably-common/protocol/agents.json`), per [RSC7d5](https://sdk.ably.com/builds/ably/specification/main/features/#RSC7d5).
- `(AIT-ST2)` `connect()` must subscribe to the cancel message name (`x-ably-cancel`) on the channel — subscribe implicitly attaches the channel — so that cancel messages from clients are routed to active runs. It must be idempotent: subsequent calls return the same promise. All run-lifecycle methods (`start`, `addMessages`, `addEvents`, `pipe`, `end`) must throw `InvalidArgument` until `connect()` resolves.

### Run Lifecycle
Expand Down Expand Up @@ -132,7 +136,11 @@ The client session manages the client-side conversation lifecycle over an Ably c

### Factory

- `(AIT-CT1)` The SDK must provide a `createClientSession` factory that accepts a channel, codec, and session options, and returns a `ClientSession`.
- `(AIT-CT1)` The SDK must provide a `createClientSession` factory that accepts an `Ably.Realtime` client, a channel name, a codec, and session options, and returns a `ClientSession`.
- `(AIT-CT1a)` On construction the client session must configure the supplied Realtime client to attribute usage to this SDK and resolve the channel by name. Configuration must be idempotent — repeated construction with the same client must leave the attribution state unchanged, so multiple sessions sharing one client are safe. The session must not close the client or release the channel on `close()`; the caller owns the client's lifecycle. The session owns its channel — callers must not also resolve the same channel name elsewhere with conflicting channel options. The attribution mechanism follows the fallback chain in `AIT-CT1a1`–`AIT-CT1a3`, modeled on chat spec [CHA-IN1](https://sdk.ably.com/builds/ably/specification/main/chat-features/#CHA-IN1).
- `(AIT-CT1a1)` Where the underlying Realtime SDK exposes a wrapper-SDK proxy mechanism (per [CHA-IN1a](https://sdk.ably.com/builds/ably/specification/main/chat-features/#CHA-IN1a)), the session must use it with `{ agents: { 'ai-transport-js': VERSION } }` and use the proxy for all subsequent channel operations.
- `(AIT-CT1a2)` Where the wrapper-SDK proxy mechanism does not exist (current ably-js), the session must inject `'ai-transport-js' -> VERSION` into the client's `options.agents` map AND pass `{ params: { agent: 'ai-transport-js/<VERSION>' } }` on `client.channels.get(channelName)`. Mirrors [CHA-IN1e](https://sdk.ably.com/builds/ably/specification/main/chat-features/#CHA-IN1e).
- `(AIT-CT1a3)` SDK authors must register the agent identifiers used here in the common repository (`ably-common/protocol/agents.json`), per [RSC7d5](https://sdk.ably.com/builds/ably/specification/main/features/#RSC7d5).
- `(AIT-CT2)` `connect()` must subscribe to the channel for incoming messages — subscribe implicitly attaches the channel (Ably RTL7g) to guarantee no messages are missed. It must be idempotent: subsequent calls return the same promise. All write methods (`send`, `regenerate`, `edit`, `update`, `cancel`, `waitForRun`) must throw `InvalidArgument` until `connect()` resolves.

### Send
Expand Down
Loading