Refresh AI Transport docs for SDK 0.2.0#3398
Merged
Merged
Conversation
This comment was marked as low quality.
This comment was marked as low quality.
zknill
force-pushed
the
zak/ait-docs-release-0.2.0
branch
from
44c3260 to
715f8c7
Compare
Bring the AI Transport docs in line with @ably/ai-transport@0.2.0,
apply an IA restructure, and rewrite the positioning and hub pages.
SDK surface alignment:
- Bump aiTransport in languageData from 0.1 to 0.2 and drop the unused
react entry.
- Sweep Turn→Run and Transport→Session terminology across every page.
ClientSession/AgentSession replace the old Transport types.
- Document the agent-minted invocationId: client mints runId and
inputEventId only; InvocationData is { runId, inputEventId,
sessionName }; the agent returns invocationId on the HTTP response.
- Document the four-event Run lifecycle (ai-run-start, ai-run-suspend,
ai-run-resume, ai-run-end) and the new 'suspended' RunInfo status.
- Remove Run.addMessages and Codec.resolveToolTarget from every page.
- Document the codec TInput/TOutput direction split, Encoder.publishInput
/ publishOutput, Decoder returning { inputs, outputs }, and the
well-known input variants.
- Switch headers to the extras.ai.transport / extras.ai.codec tier shape
and drop the legacy x-ably- prefixes from examples and prose.
- Replace ActiveRun.stream patterns (no longer in the SDK) with
session.tree.on('run', ...) lifecycle subscriptions.
- Fix recurring view.runs.filter usage to use session.view.runs() (the
ViewHandle from useView has no runs property).
- Mirror the demo's Stop-button pattern (runOf on the latest message,
non-terminal status check) wherever cancellation surfaces.
Information architecture:
- New concept pages: Runs (renamed from Turns), Connections (renamed
from Transport), Invocations, Codecs. Concept-page prose now describes
the problem the layer solves, not SDK plumbing; code samples are
restricted to one minimal proof per page.
- Split authentication: concepts/authentication keeps the three-layer
model and capability reference; getting-started/authentication has the
practical setup recipes; getting-started/channel-rules covers the
mutableMessages namespace requirement.
- API reference restructured into language groups
(JavaScript → Core SDK / Vercel, React → Core SDK / Vercel) with new
Vercel ChatTransportProvider page. Per-interface pages drop intro
frontmatter; navigational pages keep it.
- Rewrite the API reference hub (api/index.mdx) to reflect the four
entry points (@ably/ai-transport, /react, /vercel, /vercel/react) and
point to the new pages.
- Delete the use-active-turns hook page (hook removed from the SDK).
Why and positioning pages:
- Rewrite why/index.mdx around "what breaks without a durable session"
with concrete consequences (streams cannot resume, sessions do not
span devices, no way back to the agent, agents cannot recover from
restarts, no stateful capabilities), a minimal adoption snippet, and
three named capabilities (durable streaming, session continuity,
visibility and control).
- Rewrite why/http-streaming-and-ai.mdx to back the same structure.
Style and accuracy:
- Strip em dashes, bold-prefix bullets, and Latin abbreviations across
touched pages; convert several ASCII diagrams into prose.
- Fix the api='/api/chat' misuse on ClientSessionProvider examples (the
prop lives on ChatTransportProvider, not the core provider).
- Drop loadProjection, isTerminal, and the 104009 RunStartDeadlineExceeded
documentation that no longer match the SDK.
- Extend write-docs/SKILL.md templates, verification greps, and the H2
anchor convention. Add "abstract actors with generic verbs" and
"summary scaffolds" to writing-style-guide.md as AI-fingerprint
patterns to strip from drafts.
Update AIT pages to match SDK changes where the agent now mints runId (ActiveRun.runId becomes a Promise) and the Invocation wire body drops runId in favour of resolving identity from the input event's wire headers. Strip fabricated surface that was never on the SDK (view.update, turn.streamResponse / turn.end / turn.addEvents two-arg form, ClientSessionOptions api/headers/body/credentials/fetch, RunStartDeadlineExceeded, ClientSession generic missing TProjection) and replace it with the real APIs (view.sendInput with tool-result / tool-approval-response, run.pipe, run.end, run.addEvents on EventsNode[]). Swap most feature- and concept-page diagrams for new PNGs and drop the two superseded ones. Tighten prose against the style guide: remove em dashes, drop bold-prefix bullets in the agent-session message lifecycle list, and expand "owns synchronously" jargon on the invocations concept page into prose a new reader can follow.
zknill
force-pushed
the
zak/ait-docs-release-0.2.0
branch
from
73c33e6 to
e642d19
Compare
Contributor
Author
|
Claude Design canvas with all the images source: https://claude.ai/design/p/873e7016-fe22-4fe5-b306-579b700b2816?file=AI+Transport+-+Stop+and+Cancel.html&via=share |
Track SDK changes that unify the view's send surface and expose codec-message ids alongside domain messages: - View now exposes a single send() that takes TInput events; the prior sendMessage/sendInput pair is collapsed. Wrap a domain message via codec.createUserMessage to send a fresh user turn. - Codec.getMessages now returns CodecMessage<TMessage>[] (each message paired with its codecMessageId) so renderers can correlate back to the wire. ViewHandle adds getMessagesWithIds for the same purpose. - createUserMessage and createRegenerate now return TInput so factories drop straight into send(). - Add optional createToolResult, createToolResultError, and createToolApprovalResponse on the codec, each carrying a codec-defined payload. Drop the Edit input variant; edits ride the user-message path with a forkOf routing header. Also add two architecture diagrams: ait-overview.png (used on why/index.mdx as the durable-session shape) and ait-sse-stream-failures.png (used in the SSE failure section on why/http-streaming-and-ai.mdx).
Sweep every AI Transport docs page against ably-ai-transport-js to fix
wrong types, invented APIs, and outdated wording surfaced by a code
accuracy audit. The branch had drifted from the SDK during the 0.2.0
rename (transport -> session, run.suspend, codec arity changes), so
several examples no longer compiled and several APIs no longer existed.
Key corrections:
- useView option shape (drop transport, use messages not nodes) and
remove the 'aborted' codec status (the SDK ships streaming, complete,
cancelled only)
- Generic arity: View has two type params not three, ActiveRun is not
generic, AgentSession has three not four
- Drop invented APIs: ChatTransportProvider headers prop, {own: true}
cancel filter, ActiveRun.stream, invocation.runOwnerClientId,
ClientTransport, view.sendMessage / sendInput
- HITL and client-tool flows: use run.suspend() not run.end() so the
continuation can re-enter the same runId; check approval-requested,
not input-available
- Rewrite the internals codec-architecture example against the real
DecoderCoreHooks (buildStartEvents / buildDeltaEvents / buildEndEvents
/ decodeDiscrete) and the real startStream / appendStream /
closeStream lifecycle
- Wire protocol: trim HEADER_* table to what is actually exported, fix
miscounted message-name total, drop the codec-type header reference,
replace channel.updateMessage with appendMessage for stream close
- Adopt codec.createUserMessage in examples per the SDK's documented
idiomatic form, switch the why page to the pre-bound vercel factory,
and complete push-notifications.mdx with intro, Edge cases, and FAQ
so it matches the feature-page template
The three Guides pages (index, building-support-chat, building-a-copilot) existed only as untracked working-tree stubs on this branch and were removed. Drop the corresponding nav section so the build doesn't link to nonexistent pages.
rainbowFi
reviewed
Jun 8, 2026
|
|
||
| History comes from the Ably channel itself. Every message (user prompts, agent responses, lifecycle events) persists on the channel. Clients load history on connect and paginate backward through the conversation. No separate database is required. | ||
|
|
||
|  |
Contributor
There was a problem hiding this comment.
This diagram is a bit lopsided and doesn't really show how history works. I can live with it for now if the spacing is made better
rainbowFi
reviewed
Jun 8, 2026
| Modern AI chat experiences let users fork the conversation: edit an earlier prompt, regenerate a response, or branch from any point. AI Transport supports this directly. Edit and regenerate are operations on the [conversation tree](/docs/ai-transport/concepts/conversation-tree); every fork creates a sibling branch and nothing is overwritten. | ||
| Your users can revise the past without losing it. The original message stays, the new content forks alongside, and the UI flips between branches. AI Transport handles the tree shape on the wire; you wire up edit, regenerate, and the navigation arrows. | ||
|
|
||
|  |
Contributor
There was a problem hiding this comment.
This is not the right diagram for this topic (my bad, I didn't notice in the previous version). The one from the Conversation tree page would be better
rainbowFi
reviewed
Jun 8, 2026
|
|
||
| - `edit()` forks a user message. The original message and its descendants remain intact. A new child is added to the same parent, creating a sibling branch. | ||
| - `regenerate()` forks an assistant message. The original response stays in the tree, and a new sibling is created with a fresh turn. | ||
| Branches are **message-anchored** (per AITRFC-014): the branch decision lives on a `codecMessageId`, not on a `runId`. UIs render navigation arrows next to the bubble: the user's prompt for edit forks, the assistant slot for regenerate groups. |
Contributor
There was a problem hiding this comment.
Suggested change
| Branches are **message-anchored** (per AITRFC-014): the branch decision lives on a `codecMessageId`, not on a `runId`. UIs render navigation arrows next to the bubble: the user's prompt for edit forks, the assistant slot for regenerate groups. | |
| Branches are message-anchored: the branch decision lives on a `codecMessageId`, not on a `runId`. UIs render navigation arrows next to the bubble: the user's prompt for edit forks, the assistant slot for regenerate groups. |
rainbowFi
reviewed
Jun 8, 2026
| Regenerate siblings are sibling reply runs. `R1` and `R1'` share the same parent (`I1`'s `codecMessageId M1`), and `R1'.regeneratesCodecMessageId = M2` records the slot it replaces. Reply-run siblings group by shared parent; they carry no Run-level `forkOf`. | ||
|
|
||
| The tree solves this. An edit creates a sibling of the original message - both exist in the tree. A regenerate creates a sibling of the original response. Navigation between siblings lets users browse alternative branches. Nothing is ever lost. | ||
| Branch selection is message-anchored (per AITRFC-014): the branch decision lives on a `codec-message-id`, not on a `runId`. The View exposes `branchSelection(codecMessageId)` and `selectSibling(codecMessageId, index)` so a UI renders navigation arrows next to a bubble without knowing whether it is an input or a run. |
Contributor
There was a problem hiding this comment.
Suggested change
| Branch selection is message-anchored (per AITRFC-014): the branch decision lives on a `codec-message-id`, not on a `runId`. The View exposes `branchSelection(codecMessageId)` and `selectSibling(codecMessageId, index)` so a UI renders navigation arrows next to a bubble without knowing whether it is an input or a run. | |
| Branch selection is message-anchored: the branch decision lives on a `codec-message-id`, not on a `runId`. The View exposes `branchSelection(codecMessageId)` and `selectSibling(codecMessageId, index)` so a UI renders navigation arrows next to a bubble without knowing whether it is an input or a run. |
rainbowFi
reviewed
Jun 8, 2026
| --- | ||
|
|
||
| The internals section covers the wire protocol, codec architecture, conversation tree structure, and transport patterns that make up AI Transport under the hood. The audience is engineers who want to understand the system before betting on it, and contributors building custom codecs. | ||
| The internals section is for engineers who want to understand the system before betting on it, and for anyone building a custom codec. The register is precise and technical; nothing here is required to use the SDK. |
Contributor
There was a problem hiding this comment.
Suggested change
| The internals section is for engineers who want to understand the system before betting on it, and for anyone building a custom codec. The register is precise and technical; nothing here is required to use the SDK. | |
| The internals section is for engineers who want to understand the system before betting on it, and for anyone building a custom codec. Nothing here is required to use the SDK. |
Normalise the token-issuing endpoint URL across the AI Transport docs.
The authUrl placeholders ('/auth'), the "create an endpoint at" prose,
and the authCallback fetch ('/api/ably-token') now all point at
/api/auth/token for a consistent example endpoint.
Use a `conversations:` namespaced channel name in the core SDK and Vercel getting-started examples, and add a note prompting readers to match channelName to a namespace that has the AIT channel rules configured. Without a configured namespace the examples fail on the first token append, so the example channel names should reflect that requirement. Also tighten the channel-rules wording around when mutableMessages applies.
Collapse the wrapped extras.ai.transport lines in the Run sequence example onto single lines so the header maps read cleanly.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Bring the AI Transport docs in line with @ably/ai-transport@0.2.0, apply an IA restructure, and rewrite the positioning and hub pages.
SDK surface alignment:
Information architecture:
Why and positioning pages:
Style and accuracy:
Description
Checklist