Add agent session store protocols - #1686
Open
theomonnom wants to merge 10 commits into
Open
Conversation
livekit_agent_session_store.proto is the management API (Twirp): create, get, list and delete a session, plus Dump for a consistent download URL. livekit_agent_session_db.proto is the data plane: a request/response frame pair over one WebSocket per session, correlated by client-chosen request_id, with exec, query, atomic batch, interactive transactions, and credit-paced row batches so any result size streams with bounded memory at every hop. SessionValue mirrors SQLite's five storage classes. The other twirp files change only because protoc-gen-twirp numbers file descriptors by position in the invocation, so inserting one service shifts the ones after it.
|
Regenerated, so the same lines leave the Go doc comments.
paulwe
approved these changes
Jul 27, 2026
Gates the agent session store: creating, reading, querying, exporting and deleting a project's session databases, on both the management API and the data-plane connection. Without it that service could only verify that a token was signed by a key belonging to the project, not what it was allowed to do.
Query results were row-oriented: a SessionValue message per cell plus its oneof wrapper, which cost two allocations per cell on the server, the same again as the client unmarshalled, and left the garbage collector walking pointer-dense batches. A SessionColumnBatch carries a type tag per value (SQLite types values individually, not by column) plus one packed array per storage class, with text and blob bytes concatenated and addressed by exclusive end offsets rather than repeated string, which is what lets a decoder hand out subslices of one buffer. Measured end to end in the service, an 8000-row scan went from 47,819 allocations to 63, and a scalar-heavy batch is 43% smaller on the wire so more rows fit per credit. ListSessions now returns SessionSummary rather than GetSessionResponse, which drops tip from listings. tip advances on every commit, so a listing index cannot carry it without putting a write on the commit path, which means listing has to read every session's metadata row to fill it in. It is also stale on arrival, since anything acting on it must re-read. Everything else listing returns is immutable, so a summary can be served straight from an index. GetSession still returns tip for a single session. A separate message rather than leaving the field unset: 0 is a valid tip, for a session with no commits, so an unset field would be genuinely ambiguous.
An agent session is already a running conversation in this package's vocabulary (agent/livekit_agent_session.proto carries chat messages, function calls and handoffs), so agent.sessionAdmin read as authority over those rather than over the session store's databases, which is what it gates. The store's service is AgentSessionStore, so the grant now matches it.
They carried rationale from the implementation that motivated them, including Go allocation counts, which does not belong in a protocol every SDK reads. What is left states the contract: that values are typed per value rather than per column, how the text and blob offsets address a value, and that a summary has no tip.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds the two protocols the agent session store speaks. Both are new files; nothing existing changes shape.
livekit_agent_session_store.protois the management API (TwirpAgentSessionStore):CreateSession,GetSession,ListSessions,DeleteSession, andDumpfor a pre-authenticated download URL of a session consistent at a commit sequence.livekit_agent_session_db.protois the data plane: oneSessionStoreRequest/SessionStoreResponseframe pair over a single WebSocket per session, correlated by a client-chosenrequest_id. It carries exec, query, atomic batch, interactive transactions (begin/commit/rollback), cancel, and ping. Query results stream asSessionRowBatchframes paced by credits the client advertises, so any result size streams with bounded memory at every hop.SessionValuemirrors SQLite's five storage classes exactly.Why the other files changed
protoc-gen-twirpnumbers file descriptors by position within a single protoc invocation, so inserting one service shifts every file after it. The eight*.twirp.godiffs are exactly that rename, two lines each, andmagefile.goadds the two protos to the generation lists. Generated with the repo's ownmage proto.Context
This unblocks the session store service, which currently cannot build outside a local checkout of this repo.