Address code review feedback on AI agent issue proposals

Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/05ee9d02-35a9-4e04-ac53-adbbae4adbdf

Co-authored-by: pmcelhaney <51504+pmcelhaney@users.noreply.github.com>

Author: Copilot

.github/issue-proposals/agent-openapi-json-endpoint.md

@@ -26,10 +26,11 @@ Optionally, also add:
 
 ```
 GET /_counterfact/api/openapi/paths              → just the `paths` object
-GET /_counterfact/api/openapi/paths/{path}       → schema for a single path item
+GET /_counterfact/api/openapi/paths?route=<path> → schema for a single path item
+                                                    (route is URL-encoded, e.g. route=%2Fpet%2F%7BpetId%7D)
 ```
 
-to allow agents to query narrow slices without fetching the entire spec.
+The `route` query parameter avoids the routing ambiguity that would arise from embedding a slash-containing OpenAPI path into URL segments.
 
 ## Motivation
 

.github/issue-proposals/agent-request-history-endpoint.md

@@ -17,6 +17,13 @@ Adding a request-history endpoint to the Admin API gives agents a reliable, stru
 1. Add an in-memory ring buffer (e.g. last 100 entries, configurable via a `--history-size` flag or a field in `Config`) to the Koa dispatcher. After each request is handled, append a record:
 
 ```ts
+interface ValidationError {
+  location: "query" | "header" | "path" | "body";
+  name?: string;   // parameter name (for query/header/path)
+  path?: string;   // JSON Pointer (for body fields, e.g. "/price")
+  message: string; // human-readable description
+}
+
 interface HistoryEntry {
   id: number;                  // monotonically increasing
   timestamp: string;           // ISO-8601
@@ -29,7 +36,7 @@ interface HistoryEntry {
   responseHeaders: Record<string, string>;
   responseBody: unknown;
   durationMs: number;
-  validationErrors: string[];  // from the request-validator
+  validationErrors: ValidationError[];  // structured errors from the request-validator
 }
 ```
 

.github/issue-proposals/agent-scenario-save-load.md

@@ -38,7 +38,7 @@ interface Scenario {
 
 ### Behaviour
 
-- Scenarios are stored **in memory** by default (cleared on restart). Optionally, persist them to a `.counterfact-scenarios.json` file in `basePath` if a `--persist-scenarios` flag is passed.
+- Scenarios are stored **in memory** by default (cleared on restart). When `--persist-scenarios` is passed, scenarios are read from `.counterfact-scenarios.json` in `basePath` at startup (if the file exists), and every create/update/delete operation is immediately written back to that file. This means a server restarted with `--persist-scenarios` automatically restores all previously saved scenarios.
 - `POST /_counterfact/api/scenarios/:name/load` calls the existing context reset logic, then replays every entry in the scenario's `contexts` map.
 
 ### Example workflow

.github/issue-proposals/agent-seeded-random-responses.md

@@ -29,6 +29,8 @@ DELETE /_counterfact/api/config/seed    → removes the seed, restoring random b
 
 Setting the seed at runtime resets the PRNG state, so the sequence of random values produced by subsequent requests is identical to what would be produced by starting the server with that seed.
 
+The seed must be a non-negative integer (0–2³²−1). Providing a non-integer, a negative number, or a value outside this range returns `400 { "error": "seed must be a non-negative integer ≤ 4294967295" }`.
+
 ## Motivation
 
 - Agents running regression tests need stable, assertable values.

.github/issue-proposals/agent-structured-validation-errors.md

@@ -46,7 +46,10 @@ so agents (or middleware) can inspect validation errors without parsing the resp
 
 ### Config option
 
-Add a boolean `strictValidation` config option (default `false`). When `true`, validation errors immediately return `400` before the route handler is called. When `false` (the current default), the handler is still called and may choose to handle invalid input itself — but the `validationErrors` field is populated in the response if any errors exist.
+Add a boolean `strictValidation` config option (default `false`).
+
+- When `true`, validation errors immediately return `400` before the route handler is called. The response body is always `{ "error": "Validation failed", "validationErrors": […] }`.
+- When `false` (the current default), the handler is still called and its return value is used as the response body. If any validation errors exist, a top-level `validationErrors` key is added to the response body (the handler's own fields are preserved). If the handler's response body is not a JSON object (e.g. a string or array), `validationErrors` is instead delivered only via the `X-Counterfact-Validation-Errors` header to avoid mutating a non-object body.
 
 ## Motivation