rea/docs/specs/agent-environments/state-coverage/spec.md

Wider environment state coverage and tool descriptions

Issue: https://github.com/morluto/rea/issues/4933

Outcome

The environment-state view backs more read tools with state, and a served environment tells agents more about each tool. Read-only paths whose responses are not entities become documents, listed items may be identified by an …Id or …_id field, an item wrapped in a one-element array is located inside it, and reads that vary by path get their own recorded reason. Each tool description says what the tool returns and which statuses were recorded, and every MCP tool carries method hints. This increment adds no tool, view kind, provider, network activity or write effect.

Requirements

• A GET list tool (its template does not end in a parameter) that yields no item or list plan holds its latest initial value as a document when its initial reads have one request line, whether or not the capture writes its path, unless its value changed between two of those reads across any recorded write (even under another root), which leaves it fields-differ. A value whose rendered JSON exceeds 256 KiB stays rendered-oversize and is replayed from the recorded body, which itself fit. More request lines give path-varies when they differ by path (a template with a parameter before its end) and query-varies when they share one path. With every such read now a document, path-varies, query-varies, body-unusable or rendered-oversize, the unreachable not-entity reason leaves the result schema, and no-identity names item tools only. A document holds the value of its one path.
• When no path parameter proves an identity and no identity name identifies the listed items, the field-name identity is the first key of the first listed item, in its order, whose name ends in Id or _id, that every item carries as a distinct string or number, and that at least one initial recording shows distinct across two or more items. The last condition goes beyond "every item carries it distinctly": one item satisfies that vacuously, and a lone item's suffix-named fields are often foreign keys (a reaction keyed by its user, a comment by its post), so a list that only ever held one item stays a document. Empty recordings constrain no field. Identity names keep precedence, also when choosing among an envelope's arrays, where a suffix-named field identifies only an array of two or more items.
• An item response that is a root array of exactly one object, or an object with one member holding such an array, locates its entity at /0 or /<member>/0 when one of the identity names in that object repeats the path value. Objects at the root or in one member keep precedence. at and replaceAt read and replace exactly these forms besides the root and one member, so the gate and renderers run unchanged.
• An entity's state order is its earliest sighting on the timeline and it cites its records in timeline order, whichever plan observed it first.
• Each tool description reads METHOD template; <returns>; recorded statuses …; replays retained records […]; evidence ev_… after the untrusted-catalog warning. <returns> describes one level deep the first cited 2xx record replay answers as JSON: an object's fields, an array of objects' fields, or an envelope whose member lists objects, where a list is an array of objects found by the state's list rule; an empty field set reads with no fields. Only when no 2xx record replays as JSON does the first cited JSON record of another status give it, labelled status <code> returns …; with no JSON record it is omitted. The statuses are the manifest tool's statuses, the one owner of that set (no recorded status when it is empty). Field names and statuses are sampled within the description sample budget and charged with the whole description to the catalog reservation before it is retained. One owner in the environment source classifies each retained body as none, base64, cut, JSON or text; replay answers from that classification and descriptions read only its JSON case.
• MCP tools carry readOnlyHint (true for the safe methods GET, HEAD, OPTIONS and TRACE, and for query POSTs), destructiveHint: true for DELETE (unset for other writes, so the MCP default applies, and for reads, where clients ignore it), idempotentHint (true for the safe methods, PUT and DELETE) and openWorldHint: false. The tool definitions own the hints and charge them to the catalog reservation; the environment card keeps its name, description, inputSchema tool shape.

Acceptance and limits

Synthetic captures cover read-only documents, path-varies and query-varies, suffix-named identities with their key order, their two-item proof, empty first recordings and their precedence (including the choice between an envelope's arrays), a Ghost-like {"posts":[...]} item under a trailing-slash path merging with its list view, a root one-element array, a one-element filtered list that stays unidentified, and the pointer forms. The Grafana-shaped fixture covers documents for its read-only paths (its one-member team list among them) and object, array and enveloped-list descriptions; synthetic sources cover the 2xx preference over an earlier error body, the first of several JSON records, the labelled fallback, the manifest's statuses, empty, scalar and fieldless bodies, a truncated member name, a name whose JSON quoting exceeds the sample, a recorded body under 256 KiB whose rendered JSON exceeds it, non-JSON bodies and the catalog budget; the in-process and compiled MCP servers advertise the hints. A filtered list may still answer with one element whose identity name repeats the requested value; list filters, pagination, lossless big integers and cross-endpoint entity linking remain out of scope. Documents inline whole recorded values and enlarge the state result; agent tokens, CPU time and peak memory of the state and description build were not measured.

Deferred issue criteria

Serving from the state, the AgentEnv data plane and write effects remain later increments of #4933. This PR must reference rather than close the issue.