Feature/ait 1090 ait release 0 4 0

[mschristensen]

Aligns the AI Transport docs with @ably/ai-transport v0.4.0 (the changes merged to the SDK's main since 0.3.0). v0.4.0 reworks the run read-model and how an agent rebuilds conversation history, so this is largely a breaking-API sweep plus two net-new pages.

Gated on release. v0.4.0 is not on npm yet (main is untagged, package.json still 0.3.0). Code samples were written against the SDK's origin/main type declarations and cross-checked against the SDK's own in-repo docs/. Re-verify against the published package and the final CHANGELOG before merge.

Base branch is skills/docs-authoring-orchestrator (where the docs-authoring skills that produced this work live), not main.

The headline change: agents drain run.view instead of loadConversation

Run.loadConversation() is gone. An agent now rebuilds the model context by draining its leaf-pinned run.view — and it must do so before run.start():

// before (0.3.0)
await run.start();
await run.loadConversation();
const result = streamText({ messages: run.messages, ... });

// after (0.4.0)
while (run.view.hasOlder()) {   // folds the triggering input into the tree
  await run.view.loadOlder();
}
const conversation = run.view.getMessages().map(({ message }) => message);
await run.start();              // awaits run.located — now already located
const result = streamText({ messages: conversation, ... });

Ordering matters: run.start() awaits run.located, and on a cold start (agent attaches after the client published) the triggering input only folds into the tree once the caller pages run.view. Draining after start() can hang with no timeout. Database-backed hydration uses the same shape with run.view.loadUntil(seam) instead of a full drain.

run.messages no longer means "the whole conversation" — it's now this run's own turn (its triggering input + streamed output), the unit you persist.

Breaking changes swept through the docs

• ActiveRun → ClientRun; Run (agent) → AgentRun; both extend a shared BaseRun (runId, status, error, messages).
• ClientRun.runId is now synchronous (empty until run-start); await the new ClientRun.started, then read it. (await run.runId → await run.started; run.runId.)
• View split into a read base View + writable ClientView; View.selectSibling(id, i) → view.branchSelection(id).select(i) (BranchSelection → BranchHandle).
• View.loadOlder() now resolves to the revealed page (was Promise<void>); new View.loadUntil().
• ClientSessionOptions.messages seed removed; new historyPageSize.
• Agent errors unified on AgentSession.on('error') (removed AgentSessionOptions.onError); removed inputEventLookupTimeoutMs / inputEventLookbackMs / inputEventBufferLimit / rewindWindow — replaced by the passive input-event watcher and AgentRun.located.
• Error code 104010 InputEventNotFound removed.
• Already-removed-at-0.3.0 surfaces the docs still documented, now gone: Run.addEvents / EventsNode, loadProjection, RunView, MessageNode.

New pages

• features/database-hydration.mdx — the seam-reconciliation model (View.loadUntil + useMessagesWithSeed) that replaces the removed seed option: persist completed runs, reconcile stored history with the live channel on reload.
• api/react/core/use-messages-with-seed.mdx — the new hook.

Both are registered in the nav and API hub.

For reviewers

• Code accuracy is the main risk since the SDK is unreleased. Verified against the SDK's origin/main .d.ts, its in-repo docs, and the use-chat-db demo. A full docs-review-all pass (all five concerns) is green; the notable catch was the drain-before-start() ordering above.
• Pages verified as already-correct were deliberately left untouched (use-client-session, reconnection-and-recovery, optimistic-updates, human-in-the-loop, authentication).
• Known follow-ups: features/database-hydration.mdx ships prose-only (a flow diagram is a design follow-up); a pre-existing run.end(reason) positional call on the unchanged features/cancellation.mdx was left out of scope.

Relates to AIT-1090.

[coderabbitai]

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: 3c533aba-84b3-4753-8b9d-7604df35b369

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 feature/AIT-1090-ait-release-0-4-0

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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