feat: add context management support and corresponding beta handling

- Updated `computeAnthropicBetas` to include a new `context_management` option, which adds the `context-management-2025-06-27` beta when set.
- Enhanced the `buildServerToolResultBlock` documentation to reflect the new context management feature.
- Added tests to verify the correct forwarding of `context_management` and the attachment of the required beta in the adapter.
- Ensured that the beta is not added when `context_management` is null.

Closes issue #1074.

Author: harshlocham

.changeset/little-guests-trade.md

@@ -0,0 +1,8 @@
+---
+"@tanstack/ai-anthropic": patch
+---
+
+Fix `modelOptions.context_management` by attaching the required
+`context-management-2025-06-27` beta. The option was typed and forwarded on the
+request body, but Anthropic rejects context editing without the beta header —
+so the feature typechecked and could not work (issue #1074).

packages/ai-anthropic/src/adapters/text.ts

@@ -147,7 +147,8 @@ function buildServerToolResultBlock(
  * Computes the `betas` array for a Messages request. Unions:
  * - `interleaved-thinking-2025-05-14` when interleaved thinking is enabled,
  * - `code-execution-2025-08-25` when a `code_execution` tool is present,
- * - `skills-2025-10-02` when that tool carries skills.
+ * - `skills-2025-10-02` when that tool carries skills,
+ * - `context-management-2025-06-27` when `context_management` is set.
  * Returns `undefined` when none apply (so the call site omits `betas`).
  */
 export function computeAnthropicBetas(
@@ -158,6 +159,7 @@ export function computeAnthropicBetas(
           type?: 'enabled' | 'disabled' | 'adaptive'
           budget_tokens?: number
         }
+        context_management?: unknown | null
       }
     | undefined,
 ): Array<AnthropicBeta> | undefined {
@@ -169,6 +171,12 @@ export function computeAnthropicBetas(
     modelOptions.thinking.budget_tokens > 0
   if (useInterleavedThinking) betas.add('interleaved-thinking-2025-05-14')
 
+  // Context editing requires the beta header; the body field alone is not
+  // enough (issue #1074). `null` is a typed "unset" — do not enable the beta.
+  if (modelOptions?.context_management != null) {
+    betas.add('context-management-2025-06-27')
+  }
+
   // Code-execution beta is version-aware: select from the FIRST code_execution
   // tool's config type.
   const codeExecTool = tools?.find((t) => t.name === 'code_execution')

packages/ai-anthropic/tests/anthropic-adapter.test.ts

@@ -397,6 +397,29 @@ describe('Anthropic adapter option mapping', () => {
     expect(payload.max_tokens).toBe(2048)
   })
 
+  it('forwards context_management and attaches the required beta (issue #1074)', async () => {
+    mocks.betaMessagesCreate.mockResolvedValueOnce(createTextStream('ok'))
+
+    const adapter = createAdapter('claude-opus-4-1')
+    const contextManagement = {
+      edits: [{ type: 'clear_tool_uses_20250919' as const }],
+    }
+
+    for await (const _ of chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Hi' }],
+      modelOptions: {
+        context_management: contextManagement,
+      } satisfies AnthropicTextProviderOptions,
+    })) {
+      // consume stream
+    }
+
+    const [payload] = mocks.betaMessagesCreate.mock.calls[0]!
+    expect(payload.context_management).toEqual(contextManagement)
+    expect(payload.betas).toEqual(['context-management-2025-06-27'])
+  })
+
   it('forwards top-level cache_control from modelOptions instead of dropping it', async () => {
     mocks.betaMessagesCreate.mockResolvedValueOnce(createTextStream('ok'))
 

packages/ai-anthropic/tests/text.skills.test.ts

@@ -107,6 +107,36 @@ describe('computeAnthropicBetas', () => {
     expect(computeAnthropicBetas(undefined, undefined)).toBeUndefined()
   })
 
+  it('adds context-management beta when context_management is set (issue #1074)', () => {
+    const betas = computeAnthropicBetas(undefined, {
+      context_management: {
+        edits: [{ type: 'clear_tool_uses_20250919' }],
+      },
+    })
+    expect(betas).toEqual(['context-management-2025-06-27'])
+  })
+
+  it('does not add context-management beta when context_management is null', () => {
+    expect(
+      computeAnthropicBetas(undefined, { context_management: null }),
+    ).toBeUndefined()
+  })
+
+  it('unions context-management with interleaved-thinking betas', () => {
+    const betas = computeAnthropicBetas(undefined, {
+      thinking: { type: 'enabled', budget_tokens: 2048 },
+      context_management: {
+        edits: [{ type: 'clear_thinking_20251015', keep: 'all' }],
+      },
+    })
+    expect(betas).toEqual(
+      expect.arrayContaining([
+        'interleaved-thinking-2025-05-14',
+        'context-management-2025-06-27',
+      ]),
+    )
+  })
+
   it('uses code-execution-2025-05-22 beta for legacy code_execution_20250522 tool', () => {
     const tool = codeExecutionTool({
       type: 'code_execution_20250522',