Session.PrepareEvent(...) to accumulate and include with the next AppendEvent

[verdverm]

The main idea for PrepareEvent is to accumulate message parts in a cache or queue and include them with the next AppendEvent call. This allows application developers to accumulate user driven actions into a single message or event that triggers the next agent interaction or logically belong together. The pattern is the same as agents returning messages that include both text and functionCalls as parts. PrepareEvent simplifies the dev's job by mirroring this concept for their users without having to implement the accumulation themselves.

Some motivating examples

Travel Assistant:

1. User query to plan trip
2. SubAgents for flight, hotel, fun stuff
3. Need to approve full package before actually booking, may need to feedback on one or more subagents

Coding Assistant:

1. Coding assistant does work
2. User makes edits
3. User sends follow up message

I am working on a coding assistant and thinking of making the user edits look just like the same write_file tool call events it uses, but with the author set to "user", as message parts to include in the next actual message to the agent from user interaction. One might use this also for approving multiple actions (write multiple files, run multiple commands, and a whole lot more once you move beyond coding examples)

It is unclear if multiple user messages in a sequence or user tool calls are perplexing to the underlying LLMs. My understanding is they like back and forth, my motivating example is the multiple file edits with a follow up from the input box. It doesn't seem right to make user edits to the files during a session look like they were the agents. However, they do seem important to have as part of the message history, just like agent driven tool calls, so I'm keen to get them in there. The concept seems general and useful enough while being generally easy to slot in and implement.

Curious to hear others thoughts and experiences, perhaps there is a good way to do this I am not aware of yet.

---

The proposal is to add a PrepareEvent function to the session.Service interface that matches the signature of AppendEvent. Naming is hard, I have no particular attachment to this one.

Events() would return a Partial = true event as the most recent during accumulation. At least that seems the most intuitive to me, maybe another field would be better? It also occurs that we may want a way to separate accumulation depending on the author as more fluid interactions become possible throughout the stack from user to TPU.

// Service is a session storage service.
//
// It provides a set of methods for managing sessions and events.
type Service interface {
	Create(context.Context, *CreateRequest) (*CreateResponse, error)
	Get(context.Context, *GetRequest) (*GetResponse, error)
	List(context.Context, *ListRequest) (*ListResponse, error)
	Delete(context.Context, *DeleteRequest) error

	// AppendEvent is used to append an event to a session, and remove temporary state keys from the event.
	AppendEvent(context.Context, Session, *Event) error

	// PrepareEvent is used to collect message parts which are then included in the next AppendEvent.
	PrepareEvent(context.Context, Session, *Event) error
}