Add AI Transport LiveObjects docs

src/data/nav/aitransport.ts

@@ -159,6 +159,10 @@ export default {
           name: 'Agent presence',
           link: '/docs/ai-transport/features/agent-presence',
         },
+        {
+          name: 'LiveObjects State',
+          link: '/docs/ai-transport/features/liveobjects',
+        },
         {
           name: 'Push notifications',
           link: '/docs/ai-transport/features/push-notifications',

src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx

@@ -40,6 +40,7 @@ await run.start();
 | Property | Description | Type |
 | --- | --- | --- |
 | presence | The Ably presence object for the session's channel. Use it to see which clients are connected, for example to detect whether the requesting user is still online (`enter`, `leave`, `get`, `subscribe`). The session adds no semantics of its own (it is the same instance the channel exposes), and presence operations implicitly attach, so they work without first awaiting [`connect()`](#connect). | `Ably.RealtimePresence` |
+| object | The Ably LiveObjects API for the session's channel. Use it to read and write shared `LiveMap` / `LiveCounter` state on the channel the session already uses; call `get()` to resolve the object. The session adds no semantics; it is the same instance the channel exposes. Operating on it requires the client to be constructed with the `LiveObjects` plugin from `ably/liveobjects` and the object modes to be requested via [`channelModes`](#constructor-params); without both, the underlying SDK throws. See [LiveObjects State](/docs/ai-transport/features/liveobjects). | `RealtimeObject` |
 
 </Table>
 
@@ -74,6 +75,7 @@ const session = createAgentSession({
 | client | required | The Ably Realtime client. The caller owns its lifecycle; `session.close()` does not close the client. | `Ably.Realtime` |
 | channelName | required | The channel to publish to. The session owns this channel; do not also resolve it elsewhere with conflicting options. | String |
 | codec | required | The codec used to encode events and messages. | `Codec<TInput, TOutput, TProjection, TMessage>` |
+| channelModes | optional | Extra channel modes to request on top of the modes AI Transport always needs. Pass `OBJECT_MODES` to use Ably LiveObjects via [`object`](#properties). Omit to attach with the default mode set. The session requests the union, so extra modes never drop the modes AI Transport relies on. See [LiveObjects State](/docs/ai-transport/features/liveobjects). | `Ably.ChannelMode[]` |
 | logger | optional | Logger instance for diagnostic output. | `Logger` |
 | onError | optional | Called with non-fatal session-level errors not scoped to any run (cancel listener failures, channel continuity loss). | `(error: Ably.ErrorInfo) => void` |
 | inputEventLookupTimeoutMs | optional | How long `Run.start()` waits for the run's input event(s) to arrive on the channel before rejecting with `InputEventNotFound`. Defaults to 30000. | Number |

src/pages/docs/ai-transport/api/javascript/core/client-session.mdx

@@ -38,6 +38,7 @@ await session.connect();
 | tree | The complete conversation tree. Holds every known Run node and emits events on any change. Use `view` in most cases; reach for `tree` for low-level inspection. | <Table id='Tree'/> |
 | view | The default paginated, branch-aware view for rendering. Events scope to the visible messages. | <Table id='View'/> |
 | presence | The Ably presence object for the session's channel. Use it to see which clients are connected (`enter`, `leave`, `get`, `subscribe`). The session adds no semantics of its own (it is the same instance the channel exposes), and presence operations implicitly attach, so they work without first awaiting [`connect()`](#connect). | `Ably.RealtimePresence` |
+| object | The Ably LiveObjects API for the session's channel. Use it to read and write shared `LiveMap` / `LiveCounter` state on the channel the session already uses; call `get()` to resolve the object. The session adds no semantics; it is the same instance the channel exposes. Operating on it requires the client to be constructed with the `LiveObjects` plugin from `ably/liveobjects` and the object modes to be requested via [`channelModes`](#constructor-params); without both, the underlying SDK throws. See [LiveObjects State](/docs/ai-transport/features/liveobjects). | `RealtimeObject` |
 
 </Table>
 
@@ -104,6 +105,7 @@ const session = createClientSession({
 | channelName | required | The channel to subscribe to and publish cancel signals on. The session owns this channel; do not also resolve it elsewhere with conflicting options. | String |
 | codec | required | The codec used to encode and decode events and messages. | `Codec<TInput, TOutput, TProjection, TMessage>` |
 | messages | optional | Initial messages to seed the conversation tree with. Forms a linear chain. | `TMessage[]` |
+| channelModes | optional | Extra channel modes to request on top of the modes AI Transport always needs. Pass `OBJECT_MODES` to use Ably LiveObjects via [`object`](#properties). Omit to attach with the default mode set. The session requests the union, so extra modes never drop the modes AI Transport relies on. See [LiveObjects State](/docs/ai-transport/features/liveobjects). | `Ably.ChannelMode[]` |
 | logger | optional | Logger instance for diagnostic output. | `Logger` |
 
 </Table>

src/pages/docs/ai-transport/concepts/authentication.mdx

@@ -43,6 +43,7 @@ Capabilities are permissions on the Ably channel. When you issue a token for an
 | Receive streamed tokens | `subscribe` |
 | Replay history on reconnect | `subscribe`, `history` |
 | Cancel a Run | `publish` |
+| Read and write shared objects | `object-subscribe`, `object-publish` |
 | All AI Transport features | `publish`, `subscribe`, `history` |
 
 A token that's missing a capability fails silently at the operation site, not at construction. Capability mismatches are one of the most common setup mistakes; see [troubleshooting: capability or token scope mismatch](/docs/ai-transport/troubleshooting#capability-mismatch).

src/pages/docs/ai-transport/concepts/sessions.mdx

@@ -83,6 +83,8 @@ New participants join at any time. A second client attaching to the channel hydr
 
 To see which participants are currently connected, use presence: the session channel carries Ably Presence, exposed directly as `session.presence`. See [Agent presence](/docs/ai-transport/features/agent-presence).
 
+The session channel also carries Ably LiveObjects, exposed directly as `session.object`, for shared mutable state that the user and the agent both read and write, such as the page the user is on or a record they have selected. The agent reacts to it without polling, and the user sees the agent's own state change in real time. See [LiveObjects State](/docs/ai-transport/features/liveobjects).
+
 ## Support persistence models <a id="persistence"/>
 
 The channel serves two distinct roles: live delivery and historical persistence. It always serves as the live delivery layer. Whether it also serves as the historical persistence layer depends on the configuration.

src/pages/docs/ai-transport/features/agent-presence.mdx

@@ -17,7 +17,7 @@ Presence carries the status an agent *reports about itself*. For the observed fa
 
 ## How it works <a id="how-it-works"/>
 
-Both [`ClientSession`](/docs/ai-transport/api/javascript/core/client-session) and [`AgentSession`](/docs/ai-transport/api/javascript/core/agent-session) expose presence directly as `session.presence`, with the standard `enter`, `update`, `leave`, `get`, and `subscribe` operations. Presence operations attach the session's channel for you, so you can call them without first awaiting `connect()`.
+Both [`ClientSession`](/docs/ai-transport/api/javascript/core/client-session) and [`AgentSession`](/docs/ai-transport/api/javascript/core/agent-session) expose presence directly as `session.presence`, with the standard `enter()`, `update()`, `leave()`, `get()`, and `subscribe()` operations. Presence operations attach the session's channel for you, so you can call them without first awaiting `connect()`.
 
 The agent enters presence with its initial status, then updates that status as it moves through a turn (receiving a message, thinking, streaming, finishing) and leaves when it shuts down. Every connected client receives those updates in real time.
 
@@ -111,7 +111,7 @@ function AgentStatus() {
 
 ## Edge cases and unhappy paths <a id="edge-cases"/>
 
-- An agent that exits without calling `presence.leave()` (for example, a crashed process) is automatically removed from presence after a timeout. The agent is treated as present until the timeout fires. Wire a graceful shutdown that calls `leave` for the best user experience.
+- An agent that exits without calling `presence.leave()` (for example, a crashed process) is automatically removed from presence after a timeout. The agent is treated as present until the timeout fires. Wire a graceful shutdown that calls `leave()` for the best user experience.
 - A serverless agent that comes up for one turn and tears down should enter and leave presence per turn; entering once and leaving once at the end is fine for a long-running agent.
 - Presence updates do not guarantee strict ordering with channel messages. A `streaming` presence update sometimes arrives slightly after the first token. Drive the UI off `session.view.runs()` for run-level state (active, suspended, terminal) and use presence for higher-level status the agent self-reports.
 - Multi-agent setups need a unique `clientId` per agent. Two agents with the same `clientId` collide in the presence set.

src/pages/docs/ai-transport/features/liveobjects.mdx

@@ -0,0 +1,140 @@
+---
+title: "LiveObjects State"
+meta_description: "Give an AI agent live awareness of what the user is doing, and the user live awareness of what the agent is doing, with shared state on the AI Transport session channel via Ably LiveObjects."
+meta_keywords: "state sync, shared application state, LiveObjects, LiveMap, LiveCounter, session object, AI Transport, Ably, copilot"
+intro: "An agent reacts to what the user is doing, such as the page they're on or the record they've selected, without polling or extra tool calls. AI Transport session channels carry Ably LiveObjects, so agents and clients share the same live state on the channel they already use."
+redirect_from:
+  - /docs/ai-transport/sessions-identity/shared-state
+---
+
+LiveObjects State gives an agent live awareness of what its users are doing, and gives users live awareness of what the agent is doing. The agent sees the user's current state, such as the page they're on or the record they've selected, and reacts to it without polling or extra tool calls; every client sees the agent's own state change in real time. LiveObjects State uses Ably's [LiveObjects](/docs/liveobjects) through the `session.object` API on the AI Transport session, exposed on both [`ClientSession`](/docs/ai-transport/api/javascript/core/client-session) and [`AgentSession`](/docs/ai-transport/api/javascript/core/agent-session).
+
+<Aside data-type='note'>
+The conversation and the shared state do different jobs. The conversation is the running message stream, what the agent says over time. The shared state is the current value of the things both sides care about, and a participant gets it in full the moment they attach rather than by replaying history. Share only what both sides need; the agent's private reasoning stays on the server.
+</Aside>
+
+## How state sync works <a id="how-it-works"/>
+
+`session.object` is the same `RealtimeObject` the channel exposes; the session doesn't wrap it or add behaviour. It's the LiveObjects API for the channel: call `get()` to resolve the object, then read and subscribe to it as you would on a plain Ably channel. On the agent, resolve the object on a channel once and let it react to every change:
+
+<Code>
+```javascript
+// On the agent: react whenever the user's state changes.
+const myObject = await session.object.get();
+myObject.subscribe(() => groundNextResponse(myObject.compactJson()));
+```
+</Code>
+
+The client works the same object from the other end. As the user moves around the app, the client writes their current state with `myObject.set(...)`, which fires the agent's subscription. Because object state syncs on attach, a client that joins late or reloads has the current state straight away, before any conversation history loads.
+
+## Enable LiveObjects <a id="enable"/>
+
+LiveObjects is not part of the default channel mode set, so it needs explicit opt-in. Three things must line up, or `session.object` operations throw:
+
+- Construct the Ably Realtime client with the `LiveObjects` plugin from `ably/liveobjects`.
+- Request the object channel modes on the session, by passing `OBJECT_MODES` as the session's `channelModes` option.
+- Grant the connection's token the `object-subscribe` and `object-publish` capabilities. See [authentication](/docs/ai-transport/concepts/authentication#capabilities).
+
+Pass the plugin when you create the client, and the modes when you create the session:
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { LiveObjects } from 'ably/liveobjects';
+import { createClientSession, OBJECT_MODES } from '@ably/ai-transport';
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
+
+// Without the LiveObjects plugin, session.object throws.
+const ably = new Ably.Realtime({ authUrl: '/api/auth/token', plugins: { LiveObjects } });
+
+const session = createClientSession({
+  client: ably,
+  channelName: 'conversation-42',
+  codec: UIMessageCodec,
+  // Opt the session's channel into LiveObjects. The session requests these
+  // modes on top of the ones AI Transport always needs, so the transport
+  // itself is unaffected.
+  channelModes: OBJECT_MODES,
+});
+```
+</Code>
+
+`OBJECT_MODES` is `['OBJECT_SUBSCRIBE', 'OBJECT_PUBLISH']`. Channel modes replace the default set rather than adding to it, so the session requests `OBJECT_MODES` together with the modes it always needs. Opting into object modes never costs you the modes AI Transport depends on.
+
+## React to state changes on both sides <a id="read-write"/>
+
+The same object flows in both directions. The client writes the user's current state as they navigate, and renders whatever the agent sends back:
+
+<Code>
+```javascript
+const myObject = await session.object.get();
+
+// Publish the user's current view as they navigate.
+function onNavigate(path) {
+  myObject.set('currentPage', path);
+}
+
+// Render whatever the agent reports back.
+myObject.subscribe(() => renderAgentStatus(myObject.compactJson()?.agentStatus));
+```
+</Code>
+
+The agent subscribes to the same state and adapts to it. When the user opens a new page, the subscription fires with the new value, and the agent can ground its next response in the page they're actually looking at. It reports its own progress back through the same object:
+
+<Code>
+```javascript
+import { OBJECT_MODES, createAgentSession } from '@ably/ai-transport';
+
+const session = createAgentSession({
+  client: ably,
+  channelName: invocation.sessionName,
+  channelModes: OBJECT_MODES,
+});
+await session.connect();
+
+const myObject = await session.object.get();
+
+// Adapt to whatever the user is currently looking at.
+myObject.subscribe(() => {
+  const { currentPage } = myObject.compactJson() ?? {};
+  // Ground the next response in the page the user moved to.
+});
+
+// Report progress back; every subscribed client sees it.
+await myObject.set('agentStatus', 'searching flights');
+```
+</Code>
+
+Every write reaches all subscribed clients over the same channel. Concurrent writes are safe when the operation commutes: two clients calling `LiveCounter.increment` both count, but a `LiveMap.set` on the same key is last-write-wins. Partition writes by key so two writers don't race on one `set`.
+
+## Edge cases and unhappy paths <a id="edge-cases"/>
+
+- A client constructed without the `LiveObjects` plugin throws when you call `session.object`. The session does not suppress the error; construct the client with `plugins: { LiveObjects }`.
+- A session created without `channelModes: OBJECT_MODES` attaches without object modes, and object operations fail. Pass the modes when you create the session.
+- A token missing the `object-subscribe` or `object-publish` capability fails at the operation site, not at construction. The server grants only the permitted subset of requested modes. Capability scoping is part of [authentication](/docs/ai-transport/concepts/authentication#capabilities).
+- A `LiveMap.set` on a key two clients write at once is last-write-wins, so one write is lost. Partition writes by key, or use a `LiveCounter` where the values need to merge.
+
+## FAQ <a id="faq"/>
+
+### What belongs in shared state, and what belongs in the conversation? <a id="faq-what-goes-where"/>
+
+Put the state both sides act on now in `session.object`: the page the user is on, the record they've selected, a form in progress, a counter. Leave the conversation itself in the message stream, and keep the agent's private reasoning on the server. It's a shared work surface, not a transcript and not a copy of the agent's internal state.
+
+### How does the agent react to a change instead of polling? <a id="faq-react"/>
+
+`session.object.get()` gives you the object, and `subscribe` fires on every change, nested ones included. In the callback the agent reads the latest value with `compactJson()` and works from that. There's no polling loop and no extra tool call.
+
+### Why does session.object throw? <a id="faq-throws"/>
+
+One of the three requirements is missing: the `LiveObjects` plugin on the client, `channelModes: OBJECT_MODES` on the session, or the `object-subscribe` / `object-publish` capabilities on the token. See [Enable LiveObjects](#enable).
+
+### Can both the agent and the client write to the same object? <a id="faq-concurrent-writes"/>
+
+Yes. Both call the same `LiveMap` and `LiveCounter` API on `session.object`. Concurrent writes merge when the operation commutes, as with `LiveCounter.increment`; a `LiveMap.set` on the same key is last-write-wins. Partition writes by key to avoid races.
+
+## Related features <a id="related"/>
+
+- [LiveObjects](/docs/liveobjects): the Ably LiveObjects API, including `LiveMap` and `LiveCounter`.
+- [Tool calling](/docs/ai-transport/features/tool-calling): the agent asks for specific data on demand, where state sync observes it continuously.
+- [Sessions](/docs/ai-transport/concepts/sessions): `session.object` on the client and agent sessions.
+- [Agent presence](/docs/ai-transport/features/agent-presence): the same pass-through pattern for Ably Presence.