Add direct per-run session overrides

types.go

@@ -91,6 +91,15 @@ type RunRequest struct {
 	// profile is used; if both are empty, the error matches ErrProfileRequired
 	// and ErrInvalidRequest.
 	ProfileID string
+	// SessionID optionally supplies a direct per-run session identifier. A
+	// nonblank value is trimmed and overrides the prompt definition's
+	// session_id template. A blank value supplies no direct override. The
+	// maximum is 256 Unicode code points after trimming. A direct value is
+	// opaque consumer metadata, not a credential, and may be exposed in
+	// prepared values, results, collaborator requests, provider requests, and
+	// provider observability. Callers should use stable, non-sensitive
+	// identifiers.
+	SessionID string
 	// APIKey is a request-scoped direct credential. It takes precedence over
 	// APIKeyEnv, is passed to the selected LLMClient, and is never included in
 	// prepared values, results, hashes, JSON, String, or GoString output.
@@ -140,7 +149,7 @@ type PreparedRun struct {
 	StructuredOutput *StructuredOutputSpec `json:"structured_output,omitempty"`
 	// InputHashes maps every supplied input name to its opaque artifact hash.
 	InputHashes map[string]string `json:"input_hashes,omitempty"`
-	// SessionID is the trimmed rendered session identifier, if any.
+	// SessionID is the effective direct or rendered session identifier, if any.
 	SessionID string `json:"session_id,omitempty"`
 	// RenderedPromptHash is an opaque equality value for SessionID and Messages.
 	RenderedPromptHash string `json:"rendered_prompt_hash"`
@@ -179,6 +188,9 @@ type RunResult struct {
 	// PromptHash is the same opaque definition equality value exposed by
 	// PreparedRun.
 	PromptHash string `json:"prompt_hash,omitempty"`
+	// SessionID is the effective direct or rendered session identifier, if any.
+	// JSON omits an empty value.
+	SessionID string `json:"session_id,omitempty"`
 	// RenderedPromptHash is the same opaque rendered-prompt equality value
 	// computed during preparation.
 	RenderedPromptHash string `json:"rendered_prompt_hash"`
@@ -497,8 +509,8 @@ type TokenUsage struct {
 // RenderedPrompt is the fully rendered prompt passed to an LLM client and has
 // a stable JSON representation.
 type RenderedPrompt struct {
-	// SessionID is the optional trimmed session identifier rendered from the
-	// prompt definition.
+	// SessionID is the optional effective direct or rendered session
+	// identifier supplied to the model client.
 	SessionID string `json:"session_id,omitempty"`
 	// Messages contains rendered messages in definition order.
 	Messages []RenderedMessage `json:"messages"`