feat(agents): graduate sessions to agents/sessions

[mattzcarey]

Summary

• graduate the Session subsystem from src/experimental/memory/session to the canonical src/sessions boundary
• publish Session APIs and their compaction/token utilities through agents/sessions
• keep agents/experimental/memory/session and agents/experimental/memory/utils as deprecated compatibility re-exports
• move Think, examples, tests, and user-facing docs to the stable import path
• preserve Session providers, SQLite/Postgres storage behavior, context blocks, search, skills, compaction, and message protocol behavior

API

import {
  Session,
  SessionManager,
  AgentSessionProvider,
  createCompactFunction,
  estimateMessageTokens
} from "agents/sessions";

The old package paths remain valid:

import { Session } from "agents/experimental/memory/session";
import { createCompactFunction } from "agents/experimental/memory/utils";

They now re-export the canonical implementation and are documented as deprecated.

Lifecycle relationship

This follows the component-ownership direction established in #1895, but does not add another Agent lifecycle hook. Session already owns lazy, idempotent initialization through Session.create(...) and _ensureReady(), including provider initialization and hibernation restoration. Moving that logic into Agent startup would make Session less composable for direct providers and multi-session use.

The general pattern is therefore:

• the subsystem owns its initialization and storage behavior
• Agent/Think consume it through a narrow public component API
• the generic Agent lifecycle is used only when the host must coordinate a runtime phase

Compatibility

• no Session runtime or storage schema changes
• @cloudflare/think continues to re-export Session and SessionMessage
• old experimental package imports continue to resolve
• compaction and token utilities graduate with Session so stable Session examples do not depend on an experimental path

Verification

• pnpm --filter agents exec vitest --run --project workers src/tests/sessions
• pnpm --filter @cloudflare/think test:workers
• pnpm run build
• pnpm run check
• CI=true pnpm exec nx affected -t test

All checks pass. This draft is stacked on #1895 and targets feat/standardise-agent-lifecycle.

[changeset-bot]

🦋 Changeset detected

Latest commit: b7b2acb

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
agents	Minor
@cloudflare/agent-think	Patch

Not sure what this means? Click here to learn what changesets are.

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

[pkg-pr-new]

Open in StackBlitz

agents

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

@cloudflare/ai-chat

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

@cloudflare/codemode

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

create-think

npm i https://pkg.pr.new/create-think@1896

hono-agents

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

@cloudflare/shell

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

@cloudflare/think

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

@cloudflare/voice

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

@cloudflare/worker-bundler

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

commit: b7b2acb