docs + refactor: Session API documentation and AI SDK decoupling#1280
docs + refactor: Session API documentation and AI SDK decoupling#1280threepointone merged 4 commits intomainfrom
Conversation
Comprehensive guide covering Session, SessionManager, context blocks, compaction, AI tools, search, storage, and custom providers.
|
- Remove MessageQueryOptions (exported type, never accepted by any method) - Remove needsCompaction (redundant with compactAfter auto-compaction) - Remove maxContextMessages builder method and field (only fed needsCompaction) - Update docs to reflect removals
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
| export type { SkillProvider } from "./skills"; | ||
| export { isSkillProvider, R2SkillProvider } from "./skills"; | ||
| export type { MessageQueryOptions, SessionOptions } from "./types"; | ||
| export type { SessionOptions } from "./types"; |
There was a problem hiding this comment.
🟡 Missing changeset for public API removal from packages/agents
AGENTS.md requires: "Changes to packages/ that affect the public API or fix bugs need a changeset." This PR removes three public API items from packages/agents/ — the MessageQueryOptions type export (packages/agents/src/experimental/memory/session/index.ts:52), the maxContextMessages() builder method, and the needsCompaction() method on SessionManager (packages/agents/src/experimental/memory/session/manager.ts) — but does not add a changeset file describing these removals. While a pending agents: patch changeset exists from PR #1278, it documents unrelated changes (lifecycle hooks, dynamic context). Users relying on these exports (however unlikely given they were dead code) would not see the removal documented in the changelog. Additionally, experimental/session-multichat/README.md:75 still references the removed .maxContextMessages(count) method.
Was this helpful? React with 👍 or 👎 to provide feedback.
agents
@cloudflare/ai-chat
@cloudflare/codemode
hono-agents
@cloudflare/shell
@cloudflare/think
@cloudflare/voice
@cloudflare/worker-bundler
commit: |
Replace all runtime imports from the `ai` package in the Session module
with library-agnostic alternatives:
Message types:
- Define minimal SessionMessage/SessionMessagePart types that capture
only what the Session internals actually access at runtime
- Replace all `import type { UIMessage } from "ai"` with SessionMessage
across 7 session source files, 2 test files
- UIMessage from the AI SDK is structurally compatible — it can be
passed directly without conversion
- Clean up `as Record<string, unknown>` casts in session.ts since
SessionMessagePart now has the fields directly
Tool schemas:
- Swap `jsonSchema()` from `ai` to `z.fromJSONSchema()` from zod in
context.ts and manager.ts, matching the pattern from MCPClientManager
- Keep `import type { ToolSet } from "ai"` as type-only (zero runtime
cost, erased at compile time)
Consumer boundary casts:
- Add `as UIMessage[]` casts in Think, experimental session examples,
and test agents where SessionMessage[] flows into UIMessage[] sites
- Safe because underlying objects round-trip through JSON unchanged
Documentation fixes:
- Fix getBranches() doc: returns children, not siblings
- Add sessions.md to docs/index.md
- Remove stale maxContextMessages reference from session-multichat README
- Update doc to describe SessionMessage type and structural compatibility
- Add SessionMessage/SessionMessagePart to exports listing
Made-with: Cursor
threepointone
changed the title
2 participants
Summary
agents/experimental/memory/session) covering Session, SessionManager, context blocks (all 4 provider types), compaction, AI tools, search, storage schema, custom providers, and exported utilitiesMessageQueryOptions,needsCompaction(),maxContextMessages()SessionMessage/SessionMessageParttypes — Vercel AI SDK'sUIMessageis structurally compatiblejsonSchema()fromaitoz.fromJSONSchema()from zod (matchingMCPClientManager.getAITools()pattern)ToolSetas type-only import (zero runtime cost)getBranches()doc (returns children, not siblings)maxContextMessagesreference from session-multichat READMETest plan
npm run checkpasses (all 73 projects typecheck)