agentHost: centralize session and chat catalog metadata by sandy081 · Pull Request #332410 · microsoft/vscode

Sandeep Somavarapu (sandy081) · 2026-08-24T19:08:08Z

Summary

Centralizes Agent Host session-list data in agent-host.db while retaining isolated per-session and per-chat databases for data needed only after opening a conversation.

The final model has three explicit ownership boundaries:

the sessions_v2 envelope is authoritative session identity and provenance;
central session-to-chat membership is authoritative and revisioned;
the validated opaque list payload is a rebuildable aggregate cache.

Turns, drafts, annotations, attachments, detailed changesets, file-edit contents, and provider-native conversation data remain isolated in their session/chat databases.

Data ownership

Data	Authoritative owner	Central representation
Session URI, provider, creation/start time, external state, registration source	`sessions_v2` envelope in `agent-host.db`	Indexed authoritative fields
Peer-chat membership and order	`session_chat_catalogs` / `session_chats` in `agent-host.db`	Authoritative, revisioned membership
Default chat	Derived from the owning session identity	Implicit central membership
Peer-chat provider backing, origin, and inherited-turn identity	Central membership for routing; copied into the chat database so the chat remains self-contained	Authoritative routing data
Explicit session title and title source	Session metadata/state	Resolved title copied into the aggregate payload; an explicit session title wins over a computed chat title
Individual chat title and title source	That chat's database	Lightweight copy in the aggregate payload
Full session project/workspace, multi-root and folder-picker state	Session metadata/provider state	List-ready copy in the aggregate payload
Per-chat working-directory scope	Live chat/provider state; currently constrained to the owning session's workspace	Does not replace the authoritative session workspace
Session read/archive state	Session metadata/state	Resolved flags in the aggregate payload
Chat activity/status	Live chat state	Aggregated into session status/modified time and lightweight chat summaries
Primary Git/GitHub/source-control state	Session metadata/provider state for the current primary/default workspace	One primary list summary in the aggregate payload
Detailed edits and changesets	Individual session/chat databases and provider state	Only a bounded aggregate additions/deletions/files summary
Artifacts and creation provenance	Session metadata in the current model	Bounded, validated list representation
Turns, messages, drafts, attachments, annotations, reviewed files, and file-edit BLOBs	Individual session/chat databases	Not stored in the central payload

The aggregate payload is therefore a materialized list view, not a second authority. It contains resolved session presentation, primary source-control summaries, bounded artifacts/change counts, and lightweight chat summaries. If it is missing or stale, it can be rebuilt from the authoritative central registry plus provider and session/chat-local state.

Terminology note: “Chat” may later be renamed to sub-session, nested session, or runtime session.

Central catalog

Adds the independent sessions_v2 registry/catalog.
Stores a small indexed envelope plus one bounded, versioned, structurally validated payload.
Derives the TypeScript payload type from the validator.
Canonicalizes JSON before hashing so reconciliation can compare deterministic bytes.
Uses central-first listing with per-row fallback and repair when a payload is missing, stale, or unusable.
Keeps valid cached payloads when a provider is unavailable; repair never evicts the only list-visible copy.

Authoritative chat membership

Adds revisioned session_chat_catalogs and session_chats tables.
Stores ordered peer-chat URI, provider backing, origin, and inherited-turn identity centrally.
Uses compare-and-set replacement so concurrent Agent Host processes cannot silently discard each other's membership changes.
Treats the default chat as implicit in session identity.
Reads current membership exclusively from the central database during normal operation.

Each chat database remains self-contained for chat-local state. Chat titles and provider backing are persisted locally, while the central catalog retains the lightweight copies needed to enumerate, route, and present the containing session.

Downgrade compatibility

Mirrors central peer membership into the legacy peerChats session metadata during the cooling period.
Mirror failure does not roll back central authority.
Tracks exact mirrored revisions and retries stale or interrupted mirrors.
Imports membership changed by an older build during restore.
Preserves predecessor sessions registry compatibility, tombstones, exclusions, and old-build pending catalog receipts.
Supports old → new → old/intermediate → new round trips.

After the compatibility window, the legacy participant/importer and duplicated peerChats metadata can be removed without changing the central authority model.

Rebuildable aggregate

The central payload contains only list-ready session information:

resolved session title and title source;
read/archive and modified state;
project and workspace presentation;
primary Git/GitHub/source-control and change summaries;
artifacts and provenance;
lightweight ordered chat summaries.

It is rebuilt from central identity/membership, provider state, and session/chat-local metadata. Normal session listing reads the stored aggregate and does not open every conversation database.

Migration and recovery

Imports existing v2 rows, predecessor registry rows, and provider-discovered sessions by stable URI.
Supports partial and resumable migration.
Uses durable exclusions and tombstones to prevent accidental resurrection.
Uses monotonic dirty epochs to skip clean rows before opening a session database.
Performs startup and bounded safety verification for changes made by builds that do not know about dirty epochs.
Cleans up central membership and individual chat databases during durable deletion.

Validation

Fresh compile and client type-check: passed
628 affected Agent Host unit tests passing
16 existing expected pending tests
Targeted ESLint: passed
Layer validation: passed
Pre-commit hygiene: passed
Real Agent Host process compatibility matrix: 20/20 scenarios passed
- same-build restart baselines
- forward migrations
- backward compatibility
- downgrade/upgrade round trips
- crash and recovery scenarios

Scope

This does not centralize conversation history or file-edit BLOBs. The per-chat database boundary remains load-bearing for turn ordering, deletion cost, concurrency isolation, and corruption blast radius.

Add a backward-compatible sessions_v2 catalog, legacy-first synchronization receipts, reconciliation, shadow validation, central fallback reads, and durable chat metadata while retaining open-only content in per-session databases.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Adapt the sessions_v2 catalog and reconciliation work to the latest Agent Host composition, adoption, metadata, and test infrastructure changes.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Make sessions_v2 an independent current registry, import directly from current, legacy, and provider sources, mirror runtime identities for downgrade compatibility, and reconcile cross-version changes with durable exclusions and versioned markers.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Move catalog source resolution and downgrade-compatible peer chat persistence out of AgentService into focused helpers without changing migration or runtime behavior.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Introduces a centralized, verified sessions_v2 catalog for efficient Agent Host session listing, migration, downgrade compatibility, and recovery.

Changes:

Adds catalog schemas, canonical projections, synchronization receipts, migration, reconciliation, and shadow validation.
Integrates central listing with session mutations, peer chats, Git state, titles, and legacy adoption.
Adds extensive persistence, compatibility, recovery, and rollout tests.

Show a summary per file

File	Description
`src/vs/platform/agentHost/common/agent.ts`	Extends adoption results with recovered list metadata.
`src/vs/platform/agentHost/common/sessionDataService.ts`	Defines catalog synchronization receipt APIs.
`src/vs/platform/agentHost/node/agentHostBootstrap.ts`	Wires catalog persistence into bootstrap.
`src/vs/platform/agentHost/node/agentHostCatalogListReader.ts`	Converts verified catalog rows into list metadata.
`src/vs/platform/agentHost/node/agentHostCatalogProjection.ts`	Implements canonical bounded projections and hashing.
`src/vs/platform/agentHost/node/agentHostCatalogReconciliationService.ts`	Repairs interrupted or stale synchronization.
`src/vs/platform/agentHost/node/agentHostCatalogShadowValidator.ts`	Compares central and legacy listing results.
`src/vs/platform/agentHost/node/agentHostCatalogSourceResolver.ts`	Resolves canonical catalog source metadata.
`src/vs/platform/agentHost/node/agentHostCatalogSyncService.ts`	Coordinates local-first catalog synchronization.
`src/vs/platform/agentHost/node/agentHostDatabase.ts`	Adds `sessions_v2`, exclusions, and compatibility migrations.
`src/vs/platform/agentHost/node/agentHostGitStateService.ts`	Persists Git summaries through the catalog path.
`src/vs/platform/agentHost/node/agentHostPeerChatStore.ts`	Persists downgrade-compatible peer-chat membership.
`src/vs/platform/agentHost/node/agentHostServices.ts`	Registers catalog-aware persistence dependencies.
`src/vs/platform/agentHost/node/agentHostSessionTitleController.ts`	Routes title metadata through catalog synchronization.
`src/vs/platform/agentHost/node/agentHostSessionsV2MigrationService.ts`	Implements direct, resumable v2 migration.
`src/vs/platform/agentHost/node/agentService.ts`	Integrates migration, listing, synchronization, and peer chats.
`src/vs/platform/agentHost/node/agentServiceComposition.ts`	Supplies catalog persistence callbacks.
`src/vs/platform/agentHost/node/agentSessionRegistry.ts`	Adds dual-registry compatibility behavior.
`src/vs/platform/agentHost/node/agentSideEffects.ts`	Persists list-visible state changes centrally.
`src/vs/platform/agentHost/node/copilot/copilotAgent.ts`	Updates legacy adoption and metadata recovery.
`src/vs/platform/agentHost/node/localCommands/localChatCommand.ts`	Extends coordinated metadata persistence.
`src/vs/platform/agentHost/node/localCommands/renameLocalCommand.ts`	Persists title and title-source metadata together.
`src/vs/platform/agentHost/node/sessionCoordination.ts`	Integrates catalog-aware session coordination.
`src/vs/platform/agentHost/node/sessionDatabase.ts`	Adds synchronization snapshot storage and transactions.
`src/vs/platform/agentHost/test/common/sessionTestHelpers.ts`	Extends test database helpers for receipts.
`src/vs/platform/agentHost/test/node/agentHostCatalogListReader.test.ts`	Tests central row conversion and eligibility.
`src/vs/platform/agentHost/test/node/agentHostCatalogProjection.test.ts`	Tests canonicalization, limits, and verification.
`src/vs/platform/agentHost/test/node/agentHostCatalogReconciliationService.test.ts`	Tests repair and interrupted-write recovery.
`src/vs/platform/agentHost/test/node/agentHostCatalogShadowValidator.test.ts`	Tests shadow mismatch classification.
`src/vs/platform/agentHost/test/node/agentHostCatalogSourceResolver.test.ts`	Tests source and legacy metadata resolution.
`src/vs/platform/agentHost/test/node/agentHostCatalogSyncService.test.ts`	Tests synchronization ordering and recovery.
`src/vs/platform/agentHost/test/node/agentHostDatabase.test.ts`	Tests v2 schema and compatibility behavior.
`src/vs/platform/agentHost/test/node/agentHostGitStateService.test.ts`	Tests catalog-backed Git persistence.
`src/vs/platform/agentHost/test/node/agentHostPeerChatStore.test.ts`	Tests peer-chat storage and malformed data handling.
`src/vs/platform/agentHost/test/node/agentHostServices.test.ts`	Tests service dependency registration.
`src/vs/platform/agentHost/test/node/agentHostSessionTitleController.test.ts`	Tests coordinated title persistence.
`src/vs/platform/agentHost/test/node/agentHostTurnTelemetry.test.ts`	Updates telemetry fixtures for persistence wiring.
`src/vs/platform/agentHost/test/node/agentService.test.ts`	Tests rollout modes, migration, compatibility, and adoption.
`src/vs/platform/agentHost/test/node/agentServiceTestUtils.ts`	Extends AgentService database test doubles.
`src/vs/platform/agentHost/test/node/agentSessionRegistry.test.ts`	Tests dual-registry session lifecycle behavior.
`src/vs/platform/agentHost/test/node/agentSideEffects.test.ts`	Tests catalog persistence from state changes.
`src/vs/platform/agentHost/test/node/copilotAgent.test.ts`	Tests legacy adoption metadata behavior.
`src/vs/platform/agentHost/test/node/sessionCoordination.test.ts`	Tests catalog-aware coordination behavior.
`src/vs/platform/agentHost/test/node/sessionDatabase.test.ts`	Tests receipt migration and atomic persistence.
`src/vs/sessions/contrib/providers/agentHost/AGENT_HOST_SESSIONS_PROVIDER.md`	Documents the centralized catalog architecture.

Review details

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Files reviewed: 44/45 changed files
Comments generated: 7
Review effort level: Balanced

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Adopts the upstream Agent Host provider-service and chat-contribution refactors while keeping the session-catalog (Option D) work: - Rebases the durable `sessions.modified_time` column onto the sessions_v2 chain as migration 9, and adds `sessions_v2.modified_time` as migration 10 so the authoritative registry owns recency in both tables. - Threads `modifiedTime` through every sessions_v2 read, registration, envelope upsert and receipt, and makes `updateSessionModifiedTime` advance both registries in one transaction. - Moves provider registration onto `IAgentHostProviderService` while preserving catalog reconciliation scheduling and serialized discovery registrations, and routes deferred provider catalogs through the sessions_v2 importer. - Renames the catalog payload's artifact flag to `isArtifact` and adopts the upstream artifact parse contract. - Lets the catalog list reader serve the fresher of the payload and registry recency, and withholds the readable-catalog marker when an import pass leaves candidates unimported. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Connor Peet (connor4312) · 2026-08-28T15:49:19Z

+			)`,
+		].join(';\n'),
+	},
 ] as const;


These are all coming in in one PR, so they can be collapsed into a single migration.

Connor Peet (connor4312) · 2026-08-28T15:51:01Z

@@ -116,11 +226,167 @@ const migrations = [
 	},
 	{
 		version: 4,


v4 is an existing migration, you'll need to make a new one as it won't re-run

Connor Peet (connor4312) · 2026-08-28T15:54:18Z

+
+	constructor(private readonly _dependencies: IAgentHostCatalogSourceResolverDependencies) { }
+
+	async buildCatalogSyncRequest(session: URI, state: ICatalogSourceState, metadataOverrides: Readonly<Record<string, string>>, preferPersistedMetadata: boolean): Promise<IAgentHostCatalogSyncRequest> {


Seems easy to miss something here. Could we centralize metadata definitions to have like

Each session metadata being defined through some well-known ISessionMetadataKey instance that defines the key+necessary behaviors

A single array of all ISessionMetadataKey[] so this function just maps over those well-known keys?

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-09-01T08:26:47Z

Base: 91078618 Current: f67c6b50

~~No screenshot changes.~~

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…on-db-data-migration-plan

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Sandeep Somavarapu (sandy081) added 4 commits August 22, 2026 11:53

Merge origin/main into session metadata migration

bcad4c9

Adapt the sessions_v2 catalog and reconciliation work to the latest Agent Host composition, adoption, metadata, and test infrastructure changes.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

agentHost: extract session catalog helpers

1f4d679

Move catalog source resolution and downgrade-compatible peer chat persistence out of AgentService into focused helpers without changing migration or runtime behavior.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI balanced review requested due to automatic review settings August 24, 2026 19:08

Copilot started reviewing on behalf of Sandeep Somavarapu (sandy081) August 24, 2026 19:08 View session

Copilot AI reviewed Aug 24, 2026

View reviewed changes

vs-code-engineering Bot assigned Sandeep Somavarapu (sandy081) Aug 24, 2026

Sandeep Somavarapu (sandy081) and others added 6 commits August 26, 2026 10:59

agentHost: simplify session catalog persistence

b1f2a96

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Merge origin/main into session metadata migration

6a71e16

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

agentHost: remove live compatibility test harness

e7baa3e

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

agentHost: make catalog payload rebuildable

f22e651

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

agentHost: centralize session chat membership

495bfe4

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Sandeep Somavarapu (sandy081) changed the title ~~agentHost: centralize session list metadata in sessions_v2~~ agentHost: centralize session and chat catalog metadata Aug 28, 2026

Connor Peet (connor4312) reviewed Aug 28, 2026

View reviewed changes

Sandeep Somavarapu (sandy081) and others added 3 commits August 28, 2026 19:27

agentHost: address catalog review feedback

a502e17

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Merge origin/main into session database migration

ad19313

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Merge origin/main into session database migration

963a6f9

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Sandeep Somavarapu (sandy081) and others added 6 commits September 1, 2026 16:57

agentHost: bridge session catalog migration collision

9763af2

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

agentHost: migrate catalog after first listing

3c990ee

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Merge origin/main into session database migration

57e9b90

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Merge remote-tracking branch 'origin/main' into sandy081/agents/sessi…

8513b0e

…on-db-data-migration-plan

Merge remote-tracking branch 'origin/main' into sandy081/agents/sessi…

91ee991

…on-db-data-migration-plan

agentHost: preserve titles during catalog migration

65e2431

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Navigation Menu

Uh oh!

agentHost: centralize session and chat catalog metadata - #332410

agentHost: centralize session and chat catalog metadata#332410
Sandeep Somavarapu (sandy081) wants to merge 19 commits into
mainfrom
sandy081/agents/session-db-data-migration-plan

Sandeep Somavarapu (sandy081) commented Aug 24, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Connor Peet (connor4312) Aug 28, 2026

Uh oh!

Connor Peet (connor4312) Aug 28, 2026

Uh oh!

Connor Peet (connor4312) Aug 28, 2026

Uh oh!

github-actions Bot commented Sep 1, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		constructor(private readonly _dependencies: IAgentHostCatalogSourceResolverDependencies) { }

		async buildCatalogSyncRequest(session: URI, state: ICatalogSourceState, metadataOverrides: Readonly<Record<string, string>>, preferPersistedMetadata: boolean): Promise<IAgentHostCatalogSyncRequest> {

Uh oh!

Conversation

Sandeep Somavarapu (sandy081) commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Data ownership

Central catalog

Authoritative chat membership

Downgrade compatibility

Rebuildable aggregate

Migration and recovery

Validation

Scope

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Connor Peet (connor4312) Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

Connor Peet (connor4312) Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

Connor Peet (connor4312) Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Sandeep Somavarapu (sandy081) commented Aug 24, 2026 •

edited

Loading

github-actions Bot commented Sep 1, 2026 •

edited

Loading