feat: Add cache control support in langchain orchestration client

[davidkna-sap]

Context

Closes SAP/ai-sdk-js-backlog#575.

What this PR does and why it is needed

[hyperspace-insights]

Summary

The following content is AI-generated and provides a summary of the pull request:

---

feat: Add Cache Control Support in LangChain Orchestration Client

New Features

✨ Introduces prompt caching support for the @sap-ai-sdk/langchain OrchestrationClient. This enables automatic cache breakpoint injection into orchestration requests, reducing latency and token costs for repeated context in multi-turn conversations. The feature targets Anthropic Claude and Amazon Nova model families served through SAP AI Core Orchestration.

Two new capabilities are added:

1. cache_control call option — Directly pass a CacheControl directive when invoking the OrchestrationClient. A breakpoint is automatically applied to the last cacheable text block of the last message.
2. orchestrationPromptCachingMiddleware() — A new LangChain AgentMiddleware exported from @sap-ai-sdk/langchain/orchestration/prompt-caching-middleware that wraps langchain's anthropicPromptCachingMiddleware and integrates it with OrchestrationClient. Configurable with TTL (5m / 1h), message thresholds, and unsupported-model behavior (warn, ignore, raise).

Additionally, cached_tokens and cache_creation_tokens are now exposed in usage_metadata.input_token_details on LangChain orchestration responses.

Changes

• packages/langchain/src/orchestration/types.ts: Added cache_control?: CacheControl to the LangChain orchestration call options type with full JSDoc.
• packages/langchain/src/orchestration/client.ts: Applied cache_control option in both _generate and _streamResponseChunks by calling applyCacheControlToLastMessage.
• packages/langchain/src/orchestration/util.ts: Added applyCacheControlToLastMessage() which mutates the last message in a ChatMessage[] array to attach a cache breakpoint to the last cacheable content block. Also updated mapOutputToChatResult to include response_metadata.tokenUsage, input_token_details (cache read/creation), and output_token_details (reasoning tokens).
• packages/langchain/src/orchestration/prompt-caching-middleware.ts (new): Implements orchestrationPromptCachingMiddleware() by proxying the OrchestrationClient as ChatAnthropic so the upstream middleware's class-identity check passes, then delegating to anthropicPromptCachingMiddleware.
• packages/langchain/src/orchestration/prompt-caching-middleware.test.ts (new): Unit tests covering threshold logic, enableCaching flag, system prompt counting, and unsupported model behavior.
• packages/langchain/src/orchestration/util.test.ts: Added tests for applyCacheControlToLastMessage across all message roles and content types, and for prompt token details in response metadata.
• packages/langchain/package.json: Added langchain ^1.4.4 as an optional peer dependency and dev dependency; exported new ./orchestration/prompt-caching-middleware entry point.
• sample-code/src/langchain-orchestration.ts & sample-code/src/server.ts: Added invokePromptCachingAgent() sample demonstrating two sequential agent calls with cache write/read, exposed via GET /langchain/invoke-prompt-caching-agent.
• .github/workflows/build.yml: Excluded prompt-caching-middleware from the public API check path pattern.
• tsconfig.typedoc.json: Included the new middleware file in API documentation generation.
• styles/config/vocabularies/SAP/accept.txt: Added breakpoints? to the spell-check vocabulary.
• packages/core/src/stream/line-decoder.ts: Minor cleanup — replaced text[text.length - 1] with text.at(-1).
• pnpm-lock.yaml: Updated lockfile with new langchain dependency and bumped canary versions of SAP AI SDK packages.

---

• 🔄 Regenerate and Update Summary
• ✏️ Insert as PR Description (deletes this comment)
• 🗑️ Delete comment

PR Bot Information

Version: 1.26.5

• GithubContextProvider: feat: Update orchestration specification #575
• Correlation ID: f2e46b17-7e21-409a-ba9f-e6586ca4dcfd
• File Content Strategy: Full file content
• Summary Prompt: Default Prompt
• LLM: anthropic--claude-4.6-sonnet
• Event Trigger: pull_request.ready_for_review
• Output Template: Default Template

[davidkna-sap]

To be reverted after merge of SAP/cloud-sdk-js#6694

[davidkna-sap]

I added this as explicit export to avoid having to dynamically import langchain as this would have also required some manual type definitions.

[davidkna-sap]

We could also reasonably re-implement what langchain currently does, but if it becomes smarter in upstream this way we don't have to maintain this more agentic capability ourselves.