Implement support for OpenRouter sticky routing via a session_id variable

internal/domain/domain.go

@@ -47,6 +47,11 @@ const (
 	CacheControlEphemeral CacheControlType = "ephemeral"
 )
 
+const (
+	// SessionIDMaxLength is OpenRouter's documented maximum session_id length.
+	SessionIDMaxLength = 256
+)
+
 // CacheControl describes provider cache metadata attached to prompt content.
 type CacheControl struct {
 	Type CacheControlType `yaml:"type" json:"type"`
@@ -98,6 +103,7 @@ type PreparedRun struct {
 	OutputContract       OutputContract        `json:"output_contract"`
 	StructuredOutput     *StructuredOutputSpec `json:"structured_output,omitempty"`
 	InputHashes          map[string]string     `json:"input_hashes,omitempty"`
+	SessionID            string                `json:"session_id,omitempty"`
 	RenderedPromptHash   string                `json:"rendered_prompt_hash"`
 	Messages             []RenderedMessage     `json:"messages"`
 	StartTime            time.Time             `json:"start_time,omitempty"`
@@ -128,6 +134,7 @@ type PromptDefinition struct {
 	Version        string                  `yaml:"version"`
 	DefaultProfile string                  `yaml:"default_profile"`
 	Description    string                  `yaml:"description"`
+	SessionID      string                  `yaml:"session_id" json:"session_id,omitempty"`
 	Inputs         []PromptInput           `yaml:"inputs"`
 	Templates      []PromptMessageTemplate `yaml:"templates"`
 	OutputFormat   OutputFormat            `yaml:"output_format"`
@@ -189,7 +196,8 @@ type OutputContract struct {
 
 // RenderedPrompt represents the prompt after template application.
 type RenderedPrompt struct {
-	Messages []RenderedMessage `json:"messages"`
+	SessionID string            `json:"session_id,omitempty"`
+	Messages  []RenderedMessage `json:"messages"`
 }
 
 // RenderedMessage is a single message in a rendered prompt.

internal/domain/prepared_run_test.go

@@ -102,3 +102,39 @@ func TestPreparedRunJSONIncludesMessageCacheControlOnlyWhenPresent(t *testing.T)
 		t.Fatalf("expected second message to omit cache_control, got %#v", decoded.Messages[1])
 	}
 }
+
+func TestPreparedRunJSONIncludesSessionIDOnlyWhenPresent(t *testing.T) {
+	prepared := PreparedRun{
+		PromptID:          "prompt.id",
+		SelectedProfileID: "local-fast",
+		EffectiveModelParams: ExecutionTarget{
+			Endpoint: "http://llm/v1",
+			Model:    "gpt-test",
+		},
+		SessionID:          "session-123",
+		RenderedPromptHash: "rendered-hash",
+		Messages:           []RenderedMessage{{Role: "user", Content: "Summarize this."}},
+	}
+
+	b, err := json.Marshal(prepared)
+	if err != nil {
+		t.Fatalf("marshal failed: %v", err)
+	}
+
+	var decoded map[string]any
+	if err := json.Unmarshal(b, &decoded); err != nil {
+		t.Fatalf("unmarshal failed: %v", err)
+	}
+	if decoded["session_id"] != "session-123" {
+		t.Fatalf("expected session_id in prepared run JSON, got %#v", decoded["session_id"])
+	}
+
+	prepared.SessionID = ""
+	b, err = json.Marshal(prepared)
+	if err != nil {
+		t.Fatalf("marshal failed: %v", err)
+	}
+	if strings.Contains(string(b), "session_id") {
+		t.Fatalf("expected empty session_id to be omitted, got %s", b)
+	}
+}