feat(llm): split system/user prompts to enable provider-side caching

DeterministicChain now accepts WithSystemPrompt() to send a stable
System message separate from the variable User template. Providers
cache byte-identical system messages across calls (Anthropic 90%
discount, OpenAI 50%, Google 75%).

Split clarify, planning, decompose, and expand templates into
stable system prompts and per-call user templates. Bootstrap agent
templates left as-is (single-use, caching has no benefit).

Author: josephgoksu

internal/agents/core/eino.go

@@ -38,14 +38,36 @@ type DeterministicChain[T any] struct {
 	name  string
 }
 
+// ChainOption configures optional DeterministicChain behavior.
+type ChainOption func(*chainConfig)
+
+type chainConfig struct {
+	systemPrompt string
+}
+
+// WithSystemPrompt sets a stable system message prepended before the user template.
+// This enables prompt caching: providers cache the system message across calls
+// when it's byte-identical (Anthropic 90% discount, OpenAI 50%, Google 75%).
+func WithSystemPrompt(prompt string) ChainOption {
+	return func(c *chainConfig) {
+		c.systemPrompt = prompt
+	}
+}
+
 // NewDeterministicChain creates a standardized Eino chain for deterministic tasks.
 func NewDeterministicChain[T any](
 	ctx context.Context,
 	name string,
 	chatModel model.BaseChatModel,
 	templateStr string,
+	opts ...ChainOption,
 ) (*DeterministicChain[T], error) {
 
+	var cfg chainConfig
+	for _, o := range opts {
+		o(&cfg)
+	}
+
 	// 1. Template Node (Custom Lambda)
 	tmpl, err := template.New(name).Parse(templateStr)
 	if err != nil {
@@ -57,9 +79,13 @@ func NewDeterministicChain[T any](
 		if err := tmpl.Execute(&buf, input); err != nil {
 			return nil, fmt.Errorf("execute template: %w", err)
 		}
-		return []*schema.Message{
-			{Role: schema.User, Content: buf.String()},
-		}, nil
+		msgs := make([]*schema.Message, 0, 2)
+		// System message goes first (stable prefix, cached by providers).
+		if cfg.systemPrompt != "" {
+			msgs = append(msgs, schema.SystemMessage(cfg.systemPrompt))
+		}
+		msgs = append(msgs, &schema.Message{Role: schema.User, Content: buf.String()})
+		return msgs, nil
 	}
 
 	// 2. Model Node (Lambda Adapter)

internal/agents/impl/planning_agents.go

@@ -58,7 +58,8 @@ func (a *ClarifyingAgent) Run(ctx context.Context, input core.Input) (core.Outpu
 			ctx,
 			a.Name(),
 			chatModel.BaseChatModel,
-			config.SystemPromptClarifyingAgent,
+			config.ClarifyingAgentUserTemplate,
+			core.WithSystemPrompt(config.ClarifyingAgentSystemPrompt),
 		)
 		if err != nil {
 			return core.Output{}, fmt.Errorf("create chain: %w", err)
@@ -228,7 +229,8 @@ func (a *PlanningAgent) Run(ctx context.Context, input core.Input) (core.Output,
 			ctx,
 			a.Name(),
 			chatModel.BaseChatModel,
-			config.SystemPromptPlanningAgent,
+			config.PlanningAgentUserTemplate,
+			core.WithSystemPrompt(config.PlanningAgentSystemPrompt),
 		)
 		if err != nil {
 			return core.Output{}, fmt.Errorf("create chain: %w", err)
@@ -328,7 +330,8 @@ func (a *DecompositionAgent) Run(ctx context.Context, input core.Input) (core.Ou
 			ctx,
 			a.Name(),
 			chatModel.BaseChatModel,
-			config.SystemPromptDecompositionAgent,
+			config.DecompositionAgentUserTemplate,
+			core.WithSystemPrompt(config.DecompositionAgentSystemPrompt),
 		)
 		if err != nil {
 			return core.Output{}, fmt.Errorf("create chain: %w", err)
@@ -419,7 +422,8 @@ func (a *ExpandAgent) Run(ctx context.Context, input core.Input) (core.Output, e
 			ctx,
 			a.Name(),
 			chatModel.BaseChatModel,
-			config.SystemPromptExpandAgent,
+			config.ExpandAgentUserTemplate,
+			core.WithSystemPrompt(config.ExpandAgentSystemPrompt),
 		)
 		if err != nil {
 			return core.Output{}, fmt.Errorf("create chain: %w", err)

internal/config/prompts.go

@@ -490,9 +490,9 @@ CLASSIFICATION RULES:
 
 JSON ONLY, no explanation:`
 
-// SystemPromptClarifyingAgent is the system prompt for the Clarifying Agent.
-// Use with Eino ChatTemplate.
-const SystemPromptClarifyingAgent = `You are a Senior Technical Architect helping a user refine their software engineering goal.
+// ClarifyingAgentSystemPrompt is the stable system message for the Clarifying Agent.
+// Sent as a System message to enable provider-side prompt caching.
+const ClarifyingAgentSystemPrompt = `You are a Senior Technical Architect helping a user refine their software engineering goal.
 Your job is to ask clarifying questions to turn a vague request into a concrete specification.
 
 **Guidelines:**
@@ -512,26 +512,26 @@ Every question MUST include concrete options so the user can pick, modify, or ex
 Format: "[Topic]: [Option A] vs [Option B]. [Brief tradeoff]."
 This lets the user reply "first one" or "B but also add X" instead of writing paragraphs.
 
-**Input Context:**
-Goal: {{.Goal}}
-{{if .Context}}
-Architectural Knowledge:
-{{.Context}}
-{{end}}
-{{if .History}}Previous Clarifications:
-{{.History}}{{end}}
-
 **Output Format (JSON):**
 {
   "questions": ["Topic: Option A vs Option B. Tradeoff note."],
   "goal_summary": "Concise one-line summary for UI display (max 80 chars)",
   "enriched_goal": "A detailed technical specification using facts from context...",
   "is_ready_to_plan": boolean // true if sufficient info gathered
-}
-`
+}`
 
-// SystemPromptPlanningAgent is the system prompt for the Planning Agent.
-const SystemPromptPlanningAgent = `You are an Engineering Lead creating a development plan.
+// ClarifyingAgentUserTemplate is the per-call user message template (variable content).
+const ClarifyingAgentUserTemplate = `Goal: {{.Goal}}
+{{if .Context}}
+Architectural Knowledge:
+{{.Context}}
+{{end}}
+{{if .History}}Previous Clarifications:
+{{.History}}{{end}}`
+
+
+// PlanningAgentSystemPrompt is the stable system message for the Planning Agent.
+const PlanningAgentSystemPrompt = `You are an Engineering Lead creating a development plan.
 Your input is an "Enriched Goal" and relevant context from the project knowledge graph.
 Your job is to decompose this goal into a sequential list of actionable execution tasks.
 
@@ -547,10 +547,6 @@ Use the minimum number of tasks needed. Do NOT over-decompose.
 4.  **Verification**: Each task needs acceptance criteria and a validation command.
 5.  **No Overlap**: Do NOT split implementation and testing of the same feature into separate tasks. When explicit tasks are provided, use them directly.
 
-**Input Context:**
-- Enriched Goal: {{.Goal}}
-- Knowledge Graph: {{.Context}}
-
 **Output Format (JSON):**
 {
   "tasks": [
@@ -566,12 +562,17 @@ Use the minimum number of tasks needed. Do NOT over-decompose.
     }
   ],
   "rationale": "Why this approach and how it respects architectural constraints..."
-}
-`
+}`
+
+// PlanningAgentUserTemplate is the per-call user message template.
+const PlanningAgentUserTemplate = `Enriched Goal: {{.Goal}}
+
+Knowledge Graph:
+{{.Context}}`
 
-// SystemPromptDecompositionAgent is the system prompt for the Decomposition Agent.
-// Breaks enriched goals into 3-5 high-level phases for interactive planning.
-const SystemPromptDecompositionAgent = `You are an Engineering Lead decomposing a development goal into high-level phases.
+
+// DecompositionAgentSystemPrompt is the stable system message for the Decomposition Agent.
+const DecompositionAgentSystemPrompt = `You are an Engineering Lead decomposing a development goal into high-level phases.
 Break the goal into 3-5 logical phases that deliver incremental value.
 
 **Guidelines:**
@@ -580,10 +581,6 @@ Break the goal into 3-5 logical phases that deliver incremental value.
 3.  Each phase should expand into 2-4 tasks. No overlap between phases.
 4.  Use the Knowledge Graph Context to align with existing patterns and constraints.
 
-**Input Context:**
-- Enriched Goal: {{.EnrichedGoal}}
-- Knowledge Graph: {{.Context}}
-
 **Output Format (JSON):**
 {
   "phases": [
@@ -596,12 +593,17 @@ Break the goal into 3-5 logical phases that deliver incremental value.
     }
   ],
   "rationale": "Overall reasoning for this phase breakdown and sequencing..."
-}
-`
+}`
+
+// DecompositionAgentUserTemplate is the per-call user message template.
+const DecompositionAgentUserTemplate = `Enriched Goal: {{.EnrichedGoal}}
 
-// SystemPromptExpandAgent is the system prompt for the Expand Agent.
-// Generates detailed tasks for a single phase during interactive planning.
-const SystemPromptExpandAgent = `You are an Engineering Lead expanding a development phase into detailed tasks.
+Knowledge Graph:
+{{.Context}}`
+
+
+// ExpandAgentSystemPrompt is the stable system message for the Expand Agent.
+const ExpandAgentSystemPrompt = `You are an Engineering Lead expanding a development phase into detailed tasks.
 Generate 2-4 self-contained tasks that fully accomplish this phase.
 
 **Guidelines:**
@@ -611,12 +613,6 @@ Generate 2-4 self-contained tasks that fully accomplish this phase.
 4.  Use the Knowledge Graph Context to respect existing patterns and constraints.
 5.  Each task needs acceptance criteria and validation steps.
 
-**Input Context:**
-- Phase Title: {{.PhaseTitle}}
-- Phase Description: {{.PhaseDescription}}
-- Overall Goal: {{.EnrichedGoal}}
-- Knowledge Graph: {{.Context}}
-
 **CRITICAL - Constraint Compliance:**
 If the context contains architectural CONSTRAINTS (marked as CRITICAL, MUST, mandatory), ALL tasks must comply with them.
 
@@ -636,8 +632,16 @@ If the context contains architectural CONSTRAINTS (marked as CRITICAL, MUST, man
     }
   ],
   "rationale": "Why these tasks accomplish the phase and in this order..."
-}
-`
+}`
+
+// ExpandAgentUserTemplate is the per-call user message template.
+const ExpandAgentUserTemplate = `Phase Title: {{.PhaseTitle}}
+Phase Description: {{.PhaseDescription}}
+Overall Goal: {{.EnrichedGoal}}
+
+Knowledge Graph:
+{{.Context}}`
+
 
 // SystemPromptSimplifyAgent is the system prompt for the Simplify Agent.
 // Reduces code complexity and line count while preserving behavior.