Application session-listing product specification
Purpose
Applications need one authoritative session collection that can be consumed through Python, terminal, and HTTP boundaries. The collection must retain plugin-contributed presentation, ordering, and filtering behavior without requiring each adapter to understand session persistence.
Session files can be large or backed by storage that materializes content only when opened. Building every summary from complete session content on each new application runtime can therefore delay the whole collection for minutes even though session identifiers and file attributes are already available.
The target preserves the established session-list contract while allowing the service to reuse complete summaries across runtimes. When complete summaries cannot all be resolved during the implementation's foreground budget, every discovered session remains visible through the normal summary shape and later requests naturally observe completed background work.
Users
Application users need:
- stored sessions to remain discoverable when older files are slow to open;
- the newest useful session details to become available first;
- stable list ordering, titles, previews, metadata, filters, and limits;
- one malformed or unavailable session not to prevent other sessions from appearing;
- subsequent application starts not to reread every unchanged transcript.
Developers using AgentApplication need:
- one shared list and exact-summary API across adapters;
- deterministic summary and presentation shapes;
- plugin-contributed fields and ordering to compose predictably;
- structured diagnostics for invalid contributions and unreadable sessions;
- session-store implementations to expose opaque records rather than paths;
- storage and resolution mechanisms to remain replaceable without changing the public session-list API.
Server maintainers need:
- blocking storage reads isolated from request and UI threads;
- bounded background work and clean application shutdown;
- persistent derived data that cannot corrupt source sessions;
- implementation-specific configuration to remain owned by the selected implementation rather than a shared session-list configuration model.
Existing experience
AgentApplication.list_session_summaries() returns an ordered collection of
shared summaries. Each summary contains:
- an opaque session ID;
- storage modification time;
- a preview from the first non-empty user message;
- session metadata excluding provider-native transcript copies;
- application-plugin contributed fields;
- application-derived title, subtitle, and meta presentation.
Application plugins can contribute list fields and ordering through
trigger: "session_list" actions. Declarative filters operate on the ordered
summaries, and a limit applies after filtering. Exact summary lookup is
independent of list filters. Invalid actions, fields, order declarations, and
individual stored sessions produce diagnostics without failing the complete
request.
The current process-local summary cache avoids repeated loads within one application instance, but a new runtime rebuilds every summary from session content.
Target experience
On a runtime with reusable complete summaries:
- The service enumerates live session identities and attributes.
- Unchanged complete summaries are reused without opening session content.
- New or changed sessions are resolved from newest to oldest.
- The response preserves the established summary contract.
On a cold runtime backed by slow or on-demand storage:
- The service first enumerates session filenames and attributes without opening session contents.
- Full resolution begins with the most recently modified sessions.
- The implementation waits for full results only for its configured foreground interval, which defaults to ten seconds for the initial implementation.
- Fully resolved summaries appear first.
- Every remaining discovered session appears in the same response using a metadata-only summary with empty content-derived values and normal presentation fallbacks.
- Resolution continues privately after the response.
- Later list calls reuse the summaries completed in the foreground or background.
No client-specific scan state or polling protocol is required.
Acceptance examples
Reusing unchanged sessions
Given a previous application runtime derived complete summaries for stored sessions, a new runtime lists unchanged sessions without opening their complete session content.
Returning a complete membership set
Given fifty discovered session records and storage that resolves only twelve complete sessions during the foreground interval, an unfiltered unlimited request returns fifty entries. The twelve complete summaries appear before thirty-eight metadata-only summaries.
Prioritizing recent work
Given uncached sessions with different modification times, full resolution is attempted from newest to oldest. A slow older session does not prevent an already completed newer summary from being returned.
Isolating unavailable content
Given one malformed or temporarily unavailable session, the list still contains that session using fallback summary values and returns complete summaries for unaffected sessions. Diagnostics identify the failed session without exposing its content.
Preserving application-plugin behavior
Given complete summaries and valid list-trigger contributions, application plugin fields, ordering, presentation, filters, and limits retain their established results.
Goals
- Preserve the public
SessionListServiceandAgentApplicationlist interfaces. - Preserve existing complete-summary, plugin, ordering, presentation, filter, limit, exact-lookup, and diagnostic behavior.
- Return every metadata-discovered session from an unfiltered unlimited list.
- Avoid opening unchanged session content across application runtimes.
- Bound foreground full-content resolution after metadata enumeration.
- Continue unresolved work without requiring client changes.
- Keep persistence, scheduling, timeout, and storage-backend choices private and replaceable.
- Release implementation-owned resources during application close and reload.
Non-goals
- A new frontend loading, polling, progress, or scan-status protocol.
- Client package changes.
- A public cache, scanner, future, generation, or placeholder-state API.
- A shared configuration model for local cache paths, worker counts, or scan timeouts.
- A hard deadline for discovering filenames when storage blocks metadata enumeration.
- Changing the session JSON format.
- Changing session snapshot behavior.
- Requiring every future session-list implementation to use local files, SQLite, background threads, or a foreground timeout.
Session-query refinement
The separately owned session and message data query specification extends the filter contract without redefining summary construction or background resolution.
Its target adds plugin-declared timezone-aware date comparisons and exposes the same normalized filter values to local Python, one-shot CLI, HTTP, and frontend consumers. The session-list service remains authoritative for summary enrichment, ordering, conservative metadata-only filtering, limits, and diagnostics. JSONPath projection occurs only after the ordinary summary collection has been serialized.
The earlier non-goal concerning client changes remains a boundary of the metadata-only resolution correction. It does not prohibit the separately specified query capability from updating clients through their existing session-list contract.