docs(ai-transport): document interruption and steering by zknill · Pull Request #3471 · ably/docs

zknill · 2026-07-14T11:05:53Z

Documents the AI Transport interruption and steering feature, and verifies the affected agent-side docs against the SDK source (the ait-1017-steering-steps branch, the release target).

Replaces the old features/interruption.mdx with features/interruption-and-steering.mdx, covering the three change-direction patterns: steer the active Run with a follow-up prompt, cancel and re-prompt, or send alongside as a concurrent Run.
Adds a "Steer a Run" section to concepts/runs.mdx documenting the client-side steer() API ({ published, outcome }, consumed/runTerminalReason).
Repoints the nav entry ("Interruption" → "Interruption and steering") and cross-links in cancellation.mdx, concurrent-turns.mdx, double-texting.mdx, and why/index.mdx.
Fixes the agent loop in the steering page to match the SDK: createRun is synchronous (no await), drain run.view with loadOlder() before run.start(), feed run.view.getMessages() to the model (not run.messages, which is turn-only), and tear down with session.end(). Corrects a stray ActiveRun reference to ClientRun.
Fixes the cancellation page's server-side abort-signal snippet, which fed run.messages (this Run's own turn) straight to the model, losing all prior conversation context. It now drains run.view and feeds the full conversation.

coderabbitai · 2026-07-14T11:06:02Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 7b3410ed-9504-4c3e-acaa-f084313fecfc

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch zak/docs-steering

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

VeskeR · 2026-07-17T10:08:33Z

        {
-          name: 'Token streaming',
-          link: '/docs/ai-transport/features/token-streaming',
+          name: 'Agent presence',


bringing in @m-hulbert comment from #3468 regarding alphabetical ordering here:

I agree that the feature list is rapidly expanding, and it would help to make that easier to navigate; however I'm not convinced that alphabetising the list is the right way to do this. In terms of releative 'importance' - is 'Agent presence' the first thing we believe should be read to understand the value proposition and how AI Transport works?

IMO, the core value proposition should be immediately stated and clear in the "About AI Transport". "How AI Transport works" is covered by "Concepts".
And "Features" then shows you what you can build with it. If you're just skimming through the docs to see the overall feature set, I don't think there's a material difference whether "Features" is sorted alphabetically or based on our assumptions of what we deem important - people will still be able to find what they want. But when you're returning to the documentation, having the list sorted makes it way easier to navigate.

Ok, well @m-hulbert if you have a concrete proposal for an order then please share that here. In the mean time, this re-ordering makes the features findable when you want to return to a page you already know exists.

(I'm highly allergic to comments along the lines of "not this thing", without "this instead")

VeskeR

LGTM, one note about the skill change

VeskeR · 2026-07-17T16:57:10Z

 **Writing standards**

 9. Page complies with the rules in [`writing-style-guide.md`](../../../writing-style-guide.md). Use the verification greps above to spot the common violations (em dashes, bold-prefix bullets, Latin abbreviations, subjective phrases, vague modals, "we" as the subject, AI-fingerprint patterns).
-10. Author ran `/deslop` (or equivalent AI-pattern check).


I think we should keep this as item 11

it's not a shared skill, so I think this is a meaningless line

ably-ai-transport-js#267 (AIT-1039) removes the UIMessageCodec value export from @ably/ai-transport/vercel in favour of the createUIMessageCodec() factory, now generic over the AI SDK's UIMessage <metadata, data-part, tool> parameters. The change ships in the SDK 0.6.0 release, so the docs move to the factory across every AI Transport page. Stacked on #3471 (zak/docs-steering), which introduces the steering docs and already bumps the documented AIT SDK version to 0.6; this migrates every UIMessageCodec usage — including the new steering examples and the interruption-and-steering page — to createUIMessageCodec(). React provider props and multi-call snippets hold a stable codec instance; one-off sends and per-request agent handlers call the factory inline. The Vercel codec reference page is reframed around the factory (a fresh, stateless value per call), and a new "Typed messages" section on the Vercel AI SDK UI page documents threading concrete UIMessage types through the imperative path. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Replace the Interruption feature page with a combined Interruption and steering page, and add a "Steer a Run" section to the Runs concept. Repoint the nav entry and all cross-links from the old page, with a redirect_from to preserve the old URL. The page documents three ways a client changes direction mid-response: steer the active Run with a follow-up prompt, cancel and re-prompt, or send alongside as a concurrent Run.

The server-side abort-signal example fed run.messages straight to the model. run.messages is only the current Run's own turn (its triggering input plus its output), not the multi-turn conversation, so a model called with it loses all prior context. Drain run.view with loadOlder() before run.start() and feed run.view.getMessages() through convertToModelMessages, matching the agent hydration pattern used across the getting-started and interruption-and-steering pages.

Order the Features section entries by name so the nav is predictable and new pages have an obvious insertion point.

Bring the interruption and steering feature page in line with the steering API and the Vercel codec used elsewhere on the page, and capture the vocabulary rule that drove the copy edits in the write-docs skill so future drafts inherit it. - Rewrite the agent loop to use streamText + toUIMessageStream() and run.abortSignal, matching the Vercel examples used across the page - Add a "Cancel the in-flight model call" section documenting onSteer, the stepAbort/AbortSignal.any pattern, and how to tell a steer interruption apart from a genuine cancel before ending the Run - Add FAQ entries for cross-device cancel, steer persistence, batched steers, and an unreachable agent endpoint - Replace off-vocabulary terms (noun "pass", "inference pass", "projection", "RunNode") with documented product vocabulary - Rename the section to cancel-and-reprompt and fix the stale /interruption roadmap link to /interruption-and-steering - Add a "Stay inside the product vocabulary" rule, grep, and reviewer checklist item to the write-docs skill

Resolve the remaining review comments on the interruption and steering page. The steer outcome docs contradicted themselves on suspend, and two smaller items were still open. - Clarify when steer outcome resolves: a consumed steering message resolves even if the Run later suspends (runTerminalReason absent), while a not-yet-consumed message stays pending until the Run resumes and consumes it or ends. Aligns the property list with the suspended-Run edge case, which previously said outcome stays pending until the Run ends - Drop the "How does steering differ from concurrent turns?" FAQ, which only compared two of the three patterns the How it works table already covers - Rename the section heading to "Implement cancel and re-prompt" and its anchor so it matches the table row wording

Target the 0.6.0 release across the AI Transport docs so the version badge and install instructions match the SDK this branch documents. - Update the aiTransport javascript entry in the language registry to 0.6, which drives the SDK version selector badge - Bump the pinned @ably/ai-transport install in the Temporal getting-started page to ^0.6.0

Recheck the steering docs against the ably-ai-transport-js source (branch releasing as 0.6.0) and close the gaps found: - Fix the steer outcome resolution: outcome resolves at the Run's next terminal event (run-end or run-suspend), not at pipe(). - Document RunRuntime.onSteer and AgentRun.hasInput in the agent API reference. - Document the client-side ClientRun handle, including the steer() method and the SteerResult/SteerOutcome types. - Replace the coined noun "steer(s)" with "steering message" throughout, per the house style ban on invented nouns.

ably-ai-transport-js#267 (AIT-1039) removes the UIMessageCodec value export from @ably/ai-transport/vercel in favour of the createUIMessageCodec() factory, now generic over the AI SDK's UIMessage <metadata, data-part, tool> parameters. The change ships in the SDK 0.6.0 release, so the docs move to the factory across every AI Transport page. Stacked on #3471 (zak/docs-steering), which introduces the steering docs and already bumps the documented AIT SDK version to 0.6; this migrates every UIMessageCodec usage — including the new steering examples and the interruption-and-steering page — to createUIMessageCodec(). React provider props and multi-call snippets hold a stable codec instance; one-off sends and per-request agent handlers call the factory inline. The Vercel codec reference page is reframed around the factory (a fresh, stateless value per call), and a new "Typed messages" section on the Vercel AI SDK UI page documents threading concrete UIMessage types through the imperative path. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

zknill added the review-app Create a Heroku review app label Jul 14, 2026

ably-ci temporarily deployed to ably-docs-zak-docs-stee-dhtkzh July 14, 2026 11:06 Inactive

ably-ci temporarily deployed to ably-docs-zak-docs-stee-dhtkzh July 14, 2026 12:30 Inactive

zknill force-pushed the zak/docs-steering branch from 83f68ff to aac02af Compare July 17, 2026 08:04

zknill requested a review from VeskeR July 17, 2026 08:04

zknill marked this pull request as ready for review July 17, 2026 08:04

ably-ci temporarily deployed to ably-docs-zak-docs-stee-dhtkzh July 17, 2026 08:04 Inactive

This was referenced Jul 17, 2026

transport: mid-run client steering ably/ably-ai-transport-js#260

Merged

AI Transport docs: sort Features nav section alphabetically #3468

Closed

VeskeR reviewed Jul 17, 2026

View reviewed changes

zknill force-pushed the zak/docs-steering branch from aac02af to 4b72de9 Compare July 17, 2026 15:58

ably-ci temporarily deployed to ably-docs-zak-docs-stee-dhtkzh July 17, 2026 15:59 Inactive

ably-ci temporarily deployed to ably-docs-zak-docs-stee-dhtkzh July 17, 2026 16:29 Inactive

zknill requested a review from VeskeR July 17, 2026 16:48

VeskeR approved these changes Jul 17, 2026

View reviewed changes

ably-ci temporarily deployed to ably-docs-zak-docs-stee-dhtkzh July 21, 2026 14:26 Inactive

zknill force-pushed the zak/docs-steering branch from 49d1c7e to bc97c86 Compare July 21, 2026 14:26

ably-ci deployed to ably-docs-zak-docs-stee-dhtkzh July 21, 2026 14:26 View deployment

VeskeR mentioned this pull request Jul 21, 2026

docs(ai-transport): migrate UIMessageCodec to createUIMessageCodec factory #3480

Merged

zknill added 7 commits July 21, 2026 16:35

Sort AI Transport features nav alphabetically

4cf503c

Order the Features section entries by name so the nav is predictable and new pages have an obvious insertion point.

zknill force-pushed the zak/docs-steering branch from bc97c86 to 8b8ad92 Compare July 21, 2026 15:35

ably-ci temporarily deployed to ably-docs-zak-docs-stee-dhtkzh July 21, 2026 15:35 Inactive

zknill enabled auto-merge (rebase) July 21, 2026 15:35

zknill merged commit 8a44147 into main Jul 21, 2026
8 checks passed

zknill deleted the zak/docs-steering branch July 21, 2026 15:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(ai-transport): document interruption and steering#3471

docs(ai-transport): document interruption and steering#3471
zknill merged 7 commits into
mainfrom
zak/docs-steering

zknill commented Jul 14, 2026

Uh oh!

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading

Review skipped

Uh oh!

VeskeR Jul 17, 2026

Uh oh!

zknill Jul 17, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

VeskeR left a comment

Uh oh!

VeskeR Jul 17, 2026 •

edited

Loading

Uh oh!

zknill Jul 20, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

zknill commented Jul 14, 2026

Uh oh!

coderabbitai Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

VeskeR Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

zknill Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

VeskeR left a comment

Choose a reason for hiding this comment

Uh oh!

VeskeR Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zknill Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading

VeskeR Jul 17, 2026 •

edited

Loading

zknill Jul 20, 2026 •

edited

Loading