Add session and reasoning controls

docs/api.md

@@ -45,6 +45,7 @@ copyable shape. At the HTTP adapter boundary, the smallest valid shape is:
 | `prompt_id` | yes | Non-blank prompt ID. |
 | `prompt_version` | no | Prompt version filter. |
 | `profile_id` | no | Execution-profile ID; otherwise the prompt must set `default_profile`. |
+| `session_id` | no | Optional direct, non-secret session identifier. |
 | `inputs` | no | Optional object mapping input names to references. Promptkit decides whether the selected definition needs them. |
 | `vars` | no | Object mapping template-variable names to strings. |
 | `model` | no | Runtime model-override object. |
@@ -77,6 +78,12 @@ field cause `400 invalid_json`.
 inherits the selected profile, a non-empty string replaces its value, and an
 empty string explicitly clears it. JSON `null` is treated as omission.
 
+`session_id` is passed directly to Promptkit. A nonblank value replaces a
+definition-rendered session ID; omission or a blank value lets the definition
+provide one. Promptkit trims direct values and limits them to 256 Unicode code
+points. Session IDs are not credentials and may be included in prepared data,
+results, and provider-facing requests, so use stable non-sensitive identifiers.
+
 ### Strict JSON
 
 Request decoding rejects malformed JSON, unknown fields at every request level,
@@ -104,6 +111,10 @@ validation contract. The response contains:
 `total_tokens`, `cached_tokens`, and `cache_write_tokens`; unavailable
 cache usage is reported as zero.
 
+When Promptkit resolves a direct or definition-rendered session ID,
+`metadata.session_id` contains that effective result value. It is omitted when
+no effective session ID exists.
+
 A validation failure has `validation.status: "failed"`, `is_valid: false`,
 and any available diagnostic errors, while still returning the artifact and
 metadata.