Sessions as agent workflow

The staged session maps almost one-to-one onto how agent edits should land in shared data: proposed first, reviewed, then committed — never silently.

The loop

1. The agent stages. Tool calls edit documents through a session; nothing touches live data. Multi-document work accumulates as a changeset.
2. The human reviews. The UI subscribes to sys:session / sys:stage and renders pending changes live, as the agent works. Diffs are JSON patches against a known base — reviewable, attributable, droppable one by one.
3. Conflicts are data. If live documents moved underneath, the three-way preview (base / head / staged) can be fed back to the agent to resolve — amend, rebase, or drop — or surfaced to the human.
4. Commit is atomic and refusable. All staged changes land together, or the commit is refused while blocked. A discarded session leaves no trace.

Interruption-safe by construction

Because the changeset persists inside a host document — say, the conversation document driving the work — the agent process can crash, the tab can close, the session can resume tomorrow: the staged work is just document data, already synced. A natural pattern is one conversation = one host document = one changeset, so the chat and its proposed edits travel as a unit.

Hosting on the conversation doesn’t have to hand the agent the conversation: open the agent’s session with scopes excluding the hosting docType (excludeDocTypes) and the agent can neither read conversations back nor edit, rename, or delete them — staging into one is all the host-write capability buys. Add the hidden type’s schema document to excludeDocIds (sys:schema:chatConversation) and it can’t redefine the type either — the one write path the docType exclusion doesn’t cover, since a schema document is typed sys:schema rather than the type it defines. The attenuation lives on the session, so every tool call routed through it is covered without wrapping the tool surface in an app-level gate.

Both sides of the same session

Changesets sync like any document data, so a human can amend the agent’s staged change — or stage alongside it — before either of them commits. Review isn’t a modal gate; it’s two clients converging on the same staged state — the agent, for instance, running in-process on the server while the human reviews from a browser. The session treats them identically.

That extends to rich text. The agent drafts into a staged Y.Doc; the human opens a real editor bound to the same staged content and refines the draft in place — with live carets if another reviewer is in the session — and the live document still hasn’t moved. Review stops being read-only.