feat(experimental): SessionManager with chainable builder and multi-session example

[mattzcarey]

Summary

Multi-session registry built on the Session API from #1166. A single Durable Object can manage multiple independent chat sessions, each with its own messages, context blocks, and compaction history.

Stacked on #1166 — review that first.

Chainable Builder API

// In your Agent class — mirrors Session.create() pattern
const manager = SessionManager.create(this)
  .withContext("soul", { defaultContent: "You are helpful.", readonly: true })
  .withContext("memory", { description: "Learned facts", maxTokens: 1100 })
  .withCachedPrompt()
  .maxContextMessages(50);

// Each session gets auto-namespaced providers:
//   memory key: "memory_chat-123"
//   prompt key: "_system_prompt_chat-123"
const session = manager.getSession("chat-123");

// Tool separation: context tools from session, search from manager
const tools = { ...await session.tools(), ...manager.tools() };

What's in the box

SessionManager (manager.ts)

Lifecycle — create(name, opts?), get(id), list(), delete(id), rename(id, name)

• Sessions stored in assistant_sessions table with metadata: model, source, token counts, estimated cost, timestamps
• list() ordered by updated_at DESC
• delete() clears messages and FTS entries before removing the session row

Message convenience methods — all delegate to the underlying Session and call _touch() to update updated_at

• append(sessionId, message, parentId?)
• upsert(sessionId, message, parentId?) — check-then-update, actually updates existing messages (not INSERT OR IGNORE which silently drops)
• appendAll(sessionId, messages, parentId?)
• deleteMessages(sessionId, messageIds) — scoped to a specific session, not broadcast across all cached sessions
• clearMessages(sessionId)
• getHistory(sessionId, leafId?)

Branching

• fork(sessionId, atMessageId, newName) — creates a new session with parentSessionId lineage, copies the message path up to atMessageId with fresh UUIDs, calls _touch() so the fork sorts correctly in list()
• getBranches(sessionId, messageId) — convenience wrapper

Compaction

• needsCompaction(sessionId) — delegates to Session.needsCompaction(maxContextMessages)
• addCompaction(sessionId, summary, fromId, toId) / getCompactions(sessionId)
• compactAndSplit(sessionId, summary, newName?) — marks old session with end_reason = 'compaction', creates new session with summary as first message. Useful for "fresh start" compaction strategy

Usage tracking — addUsage(sessionId, inputTokens, outputTokens, cost) for cost monitoring

Cross-session search — search(query, { limit? }) uses the shared assistant_fts table

• tools() returns session_search tool for AI to search across all sessions

Lazy init pattern

Same pattern as Session.create() — SessionManager.create() uses Object.create(SessionManager.prototype) to bypass the constructor, storing pending config. _ensureReady() resolves on first use. The _ensureTable() method creates both assistant_sessions AND assistant_fts tables so cross-session search works even before any session's AgentSessionProvider has initialized.

multi-session-agent example

Full working example with:

• Sidebar with chat list (create, delete, switch)
• Per-session context blocks (soul + memory) with update_context tool
• Cross-session FTS search via session_search tool
• Auto-compaction after 6 messages with iterative compaction support (filters synthetic compaction_ IDs, uses getCompactions()[0].fromMessageId for superseding overlays)
• Workers AI (Kimi K2.5)

Design decisions for reviewers

1. deleteMessages(sessionId, messageIds) takes a session ID — Devin flagged the original design which broadcast deletes across all in-memory cached sessions. This was wrong: uncached sessions were silently skipped, and it didn't call _ensureReady(). Now targets a specific session directly.

2. fork() calls _touch() — Without this, forked sessions had their updated_at stuck at creation time, causing them to sort incorrectly in list() (which orders by updated_at DESC).

3. upsert() uses check-then-update — Not INSERT OR IGNORE which silently drops updates to existing messages. Actually calls updateMessage() if the message already exists.

4. Tool separation — session.tools() returns update_context (per-session context blocks), manager.tools() returns session_search (cross-session FTS). Combined with spread: { ...await session.tools(), ...manager.tools() }.

5. FTS table in _ensureTable() — The manager creates the assistant_fts virtual table alongside assistant_sessions, so search() works even if no session's AgentSessionProvider has been initialized yet.

6. No changeset — This is under experimental/ — API will change between releases.

Stack

1. feat(experimental): Session API with chainable builder #1166 Session API core ← main
2. this PR ← feat(experimental): Session API with chainable builder #1166
3. feat(think): integrate agents Session API #1169 Think integration ← this

Test plan

16 DO-backed tests covering:

• Session isolation: messages, compaction overlays, system prompt, clear — all scoped to session ID
• Manager CRUD: create/get, list ordering, delete (clears messages), rename
• Cross-session search: FTS across sessions, session_search tool
• Context blocks: replace/append/get proxies, AgentContextProvider persistence
• deleteMessages targets specific session — deletes from one session, verifies other is unaffected
• fork updates updated_at — verifies timestamp, parent lineage, and copied message count
• Iterative compaction filters synthetic IDs — two rounds of compaction, verifies second supersedes first using only real message IDs

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4feb33e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 9 additional findings in Devin Review.

[devin-ai-integration]

🔴 Missing changeset for new public API exports in packages/agents

The PR adds SessionManager, SessionInfo, and SessionManagerOptions as new public exports from agents/experimental/memory/session (packages/agents/src/experimental/memory/session/index.ts:69-73), which is a published npm entry point. Per the repository's AGENTS.md rules: "Changes to packages/ that affect the public API or fix bugs need a changeset." No changeset file for this change exists in .changeset/ — the only existing changeset (workflow-local-dev-lifecycle.md) is for an unrelated workflow change.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[mattzcarey]

Intentionally skipped — this is under experimental/ which is explicitly excluded from changeset requirements. The API will change between releases.

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@1167

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@1167

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@1167

hono-agents

npm i https://pkg.pr.new/hono-agents@1167

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@1167

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@1167

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@1167

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@1167

commit: 9f59d05

[mattzcarey]

/bonk review

[ask-bonk]

Review: SessionManager with chainable builder and multi-session example

Thorough review of the SessionManager implementation, multi-session example, and test suite. Most of the issues Devin flagged in earlier rounds appear to have been addressed (parentSessionId in fork, FTS table creation in _ensureTable, upsert check-then-update, deleteMessages scoped to session, fork _touch, env.d.ts references). The remaining open issue and a few additional observations follow.

Open issue: Shared compactFn closure leaks previousSummary across sessions

Devin's most recent unresolved finding is correct. In experimental/multi-session-agent/src/server.ts:33-39, a single compactFn is created at the class field level. createCompactFunction (packages/agents/src/experimental/memory/utils/compaction-helpers.ts:435) captures a previousSummary closure variable that persists across all calls. When session A is compacted, previousSummary is set to session A's summary. When session B is later compacted, session A's summary is passed to buildSummaryPrompt as prior context, cross-contaminating sessions.

The fix is straightforward — use a per-session compact function. For example:

private compactFns = new Map<string, (msgs: UIMessage[]) => Promise<UIMessage[]>>();

private getCompactFn(chatId: string) {
  let fn = this.compactFns.get(chatId);
  if (!fn) {
    fn = createCompactFunction({
      summarize: (prompt) =>
        generateText({ model: this.getAI(), prompt }).then((r) => r.text),
      protectHead: 1,
      minTailMessages: 2,
      tailTokenBudget: 100
    });
    this.compactFns.set(chatId, fn);
  }
  return fn;
}

Then at line 135: this.getCompactFn(chatId)(history) instead of this.compactFn(history).

This is in the example, not the core SDK, so it won't affect library consumers, but since this example is user-facing learning material it should demonstrate correct patterns.

Minor observations

1. README is stale — experimental/multi-session-agent/README.md shows a ChatAgent class name and a single-session Session API example (with compaction.tokenThreshold, session.append(), session.getMessages()). None of this matches the actual MultiSessionAgent + SessionManager implementation. Since users will look at this to understand the example, it should be updated or at minimum show the SessionManager.create() builder pattern.

2. search() FTS error handling — SessionManager.search() at manager.ts:347-360 uses MATCH directly on user input. FTS5 MATCH syntax is strict — characters like *, ", or unbalanced parens in the query will throw a SQLite error. The tools() method wraps the call in try/catch (line 384), which is good, but direct callers of manager.search(query) would get an unhandled exception. Worth considering input sanitization or a try/catch in search() itself.

3. delete() doesn't call _ensureReady() — SessionManager.delete() at manager.ts:185-189 calls this.getSession(sessionId).clearMessages() which triggers _ensureReady() indirectly via getSession(), but if the session table hasn't been created yet (edge case with builder pattern), the subsequent DELETE FROM assistant_sessions could fail. Not a practical concern since you'd normally create before deleting, but inconsistent with other lifecycle methods that call _ensureReady() explicitly.

4. UIMessage parts type assertion — In server.ts:104, the tool part construction uses as unknown as UIMessage["parts"][number] to force-cast. This works but hides type incompatibilities. If the UIMessage type changes upstream, this won't produce a compile error.

5. compactAndSplit summary message role — At manager.ts:317, the summary is inserted as an assistant role message with "[Context from previous session]" prefix. This is a design choice, but it means the new session starts with an assistant message before any user message, which some LLM APIs may handle differently.

Test coverage

The 16 DO-backed tests plus the pure unit tests provide solid coverage of the core functionality. The iterative compaction test (testManagerCompactionFiltersSyntheticIds) is particularly valuable — it validates the tricky synthetic ID filtering across multiple compaction rounds.

Overall

The SessionManager is a clean, well-structured registry layer on top of the Session API. The builder pattern mirrors Session.create() nicely, and the lazy init / table creation strategy is sound. The main actionable item is the shared compactFn closure in the example.

[ask-bonk]

The shared compactFn closure captures a previousSummary variable (compaction-helpers.ts:435) that persists across all calls. When session A is compacted, previousSummary gets set to session A's summary. When session B is compacted later, buildSummaryPrompt receives session A's summary as context, cross-contaminating sessions.

Fix: use a per-session compact function via Map<string, ...> keyed by chatId, and lazily create in a getCompactFn(chatId) helper. Then call this.getCompactFn(chatId)(history) at line 135 instead of this.compactFn(history).

[ask-bonk]

The README still shows the old ChatAgent class with a single-session Session API (compaction.tokenThreshold, session.append(), session.getMessages()). Since the example now uses MultiSessionAgent + SessionManager, this should be updated to reflect the actual builder pattern and multi-session architecture.

[ask-bonk]

Review posted on PR #1167. Here's a summary of what was submitted:

PR-level review comment covering the full analysis, and two inline comments:

1. server.ts:39 — The shared compactFn closure leaks previousSummary across sessions. This is the main actionable bug. The createCompactFunction captures a single previousSummary variable that persists across all calls, so compacting session A contaminates session B's compaction prompt. Fix: use a Map<string, ...> keyed by chatId to create per-session compact functions.

2. README.md:46 — The README is stale, still showing ChatAgent with the old single-session API instead of the actual MultiSessionAgent + SessionManager builder pattern.

Additional minor observations in the PR-level comment:

• FTS MATCH on unsanitized user input in search() can throw on special characters
• delete() doesn't explicitly call _ensureReady()
• UIMessage parts force-cast via as unknown as hides type incompatibilities
• compactAndSplit starts new sessions with an assistant message before any user message

The previously flagged issues (fork parentSessionId, FTS table in _ensureTable, upsert semantics, deleteMessages scoping, fork _touch, env.d.ts naming) were all confirmed as resolved in subsequent commits.

github run

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 20 additional findings in Devin Review.

[devin-ai-integration]

🟡 SessionManager.delete() leaks context block data in cf_agents_context_blocks

When SessionManager.delete(sessionId) is called, it clears messages (assistant_messages), compactions (assistant_compactions), FTS entries (assistant_fts), and the session row (assistant_sessions). However, it does not clean up the namespaced context block data stored in cf_agents_context_blocks. Each session creates rows with keys like memory_<sessionId> and _system_prompt_<sessionId> (via AgentContextProvider at packages/agents/src/experimental/memory/session/providers/agent-context.ts:49-53). These rows are orphaned on delete and accumulate over time as sessions are created and destroyed within the same Durable Object.

Prompt for agents

In packages/agents/src/experimental/memory/session/manager.ts, the delete() method at lines 185-189 should also clean up context block data from cf_agents_context_blocks. The context blocks are stored with namespaced keys like `memory_<sessionId>` and `_system_prompt_<sessionId>` (constructed in Session._ensureReady at packages/agents/src/experimental/memory/session/session.ts:110 and session.ts:128). After calling clearMessages(), add SQL to delete all context block rows whose label ends with `_<sessionId>`. For example:

this.agent.sql`DELETE FROM cf_agents_context_blocks WHERE label LIKE ${'%_' + sessionId}`;

Alternatively, have each Session track its context block keys and expose a clearContext() method that the manager can call during deletion.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 24 additional findings in Devin Review.

[devin-ai-integration]

🟡 SessionManager.withCachedPrompt(provider) shares one prompt store across all sessions

When a concrete ContextProvider is passed to SessionManager.withCachedPrompt(provider), it is forwarded verbatim to every Session created by getSession() (line 147). This means all sessions share the same prompt store: when session A calls freezeSystemPrompt(), it writes its prompt to the shared store; when session B later calls freezeSystemPrompt(), it reads session A's prompt from that same store (packages/agents/src/experimental/memory/session/context.ts:244-246). This silently causes cross-session prompt contamination. In contrast, when called without arguments (withCachedPrompt()), each session correctly gets its own namespaced AgentContextProvider.

Prompt for agents

In packages/agents/src/experimental/memory/session/manager.ts, the getSession() method at lines 144-148 passes a shared ContextProvider to all sessions when _cachedPrompt is a concrete provider. Either:
1. Remove the ability to pass a concrete provider to SessionManager.withCachedPrompt() (only allow the boolean true case), since per-session namespacing is required, OR
2. Wrap the user-provided provider with per-session namespacing, e.g. by creating a new ContextProvider per session that delegates to the user's provider with a session-scoped key.

---

Was this helpful? React with 👍 or 👎 to provide feedback.