add anthropic caching to system prompt in agent (#1655)

# Add Anthropic Prompt Caching for Agent System Prompts

## Summary

Added Anthropic's ephemeral cache control to system prompts in
`v3AgentHandler.ts`. Refactored into a single `prependSystemMessage()`
function used by both `execute()` and `stream()`.

## Why

Reduces token costs and latency for Claude models by caching the system
prompt server-side. The `providerOptions` are ignored by non-Anthropic
models, so this is safe for all providers.

## Limitations

Currently limited to the system prompt only. Extending to conversation
messages requires restructuring message processing to insert cache
breakpoints at stable boundaries.

## Test Plan

- [x] Verify agent works with Claude and non Anthropic models
- [x] Confirm `cached_input_tokens` appears in usage metrics with Claude


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added Anthropic ephemeral caching to the agent’s system prompt to lower
Claude token usage and reduce latency. Safe for non-Anthropic models;
the options are ignored.

- **New Features**
- System messages now include Anthropic providerOptions with
cacheControl: ephemeral.

- **Refactors**
- Introduced prependSystemMessage() and used it in both text generation
and streaming to centralize system prompt handling.

<sup>Written for commit 6e2eef6.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1655">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->

Author: tkattkat

packages/core/lib/v3/handlers/v3AgentHandler.ts

@@ -42,6 +42,28 @@ function getErrorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+/**
+ * Prepends a system message with cache control to the messages array.
+ * The cache control providerOptions are used by Anthropic and ignored by other providers.
+ */
+function prependSystemMessage(
+  systemPrompt: string,
+  messages: ModelMessage[],
+): ModelMessage[] {
+  return [
+    {
+      role: "system",
+      content: systemPrompt,
+      providerOptions: {
+        anthropic: {
+          cacheControl: { type: "ephemeral" },
+        },
+      },
+    },
+    ...messages,
+  ];
+}
+
 export class V3AgentHandler {
   private v3: V3;
   private logger: (message: LogLine) => void;
@@ -289,8 +311,7 @@ export class V3AgentHandler {
 
       const result = await this.llmClient.generateText({
         model: wrappedModel,
-        system: systemPrompt,
-        messages,
+        messages: prependSystemMessage(systemPrompt, messages),
         tools: allTools,
         stopWhen: (result) => this.handleStop(result, maxSteps),
         temperature: 1,
@@ -414,8 +435,7 @@ export class V3AgentHandler {
 
     const streamResult = this.llmClient.streamText({
       model: wrappedModel,
-      system: systemPrompt,
-      messages,
+      messages: prependSystemMessage(systemPrompt, messages),
       tools: allTools,
       stopWhen: (result) => this.handleStop(result, maxSteps),
       temperature: 1,