feat(gateway): name the role and call behind each change to an env's state

[sarah-chitty-1]

What

Name the role and the call behind each change to an env's state, so a verifier can tell the agent's changes from a trigger's, a user sim's or an executor's.

Today the before/after state diff says what changed but not who changed it. A task with triggers or a user sim can't separate "the agent sent this email" from "a trigger delivered this email".

• Every write the gateway serves records the changelog rows it spanned (ids before and after the call), in the trajectory:
  • Tool calls: the result event gains changelog_id_before next to the existing changelog_id. A call that fails is logged as tool_call_failed with both ids, so a write it committed before failing still names it (failed: true).
  • Trigger tool actions: already recorded both ids.
  • Requests through the /svc and /website proxy: new http_request trajectory events, with role, route, service, method, path, status, the trigger fires the request was made for, and the two ids.
• A request's window closes when the response finishes, not when its headers arrive. An MCP call over SSE sends headers first and writes afterwards. Only a request that wrote rows is logged.
• New GET /changes (urn:agentenv:changes/v1, on the card): the env's changelog rows, each listing its actors. Paged with after_id and limit.
  • one actor: the row was written by exactly one call
  • several: calls overlapped (performance mode runs them concurrently)
  • none: the gateway didn't serve that write
• snapshot_env gets include_env_changes, next to include_env_trajectory. It saves the attributed rows as JSONL and records them under metadata["env_changes"][env_id].

Why at the gateway: it's the one component that sees both the caller (role, tool or request, trigger fire) and the changelog. Writing the actor into the changelog table itself would need every service, including ones outside this repo, to tag its own database connections.

Worth a look

1. No change to existing fields: an empty changelog still reads null in /state, /step responses and the trajectory. The attribution reads a null id before a call as an empty changelog; if that one read failed while the one after succeeded, earlier rows would also list this call, as an extra actor.
2. Trajectory size: an http_request event is written only when a proxied non-GET request actually wrote changelog rows, so POST reads, MCP handshakes and loads before the changelog triggers go in add nothing. The trajectory's consumers here and in the hub count only tool_call events or copy it verbatim.
3. Streaming: a request's window closes when its response has ended. The body streams through as before; the event is logged after the last byte (tested with a held-open stream).
4. Precision: consistent mode serializes tool calls, so their windows are exact. It doesn't serialize proxied writes. Should it?
5. Restarts: windows are kept in memory from gateway start. A restart loses attribution for earlier rows, though the trajectory file keeps them.
6. Possible existing gap: in the test website env, the backend's message POST produced no changelog row at all, while MCP tool writes did. That suggests a changelog-coverage gap for website envs; not chased here.
7. Merge order: this and feat(triggers): fire env triggers on requests to the env's websites #237 touch the same proxy path. Whichever merges second needs a quick rebase.

Tests

• Unit: tst/unit/env/gateway/changes_test.py (new): the join, the recorded windows, a stream not held back by its window, a write-less request not logged, null kept for an empty changelog, and the three Greptile cases (a gateway-native read claims no earlier row, a failed call keeps its write and its error, a request keeps the trigger fire it started under). test_snapshot_env.py, gateway_card_test.py and test_env.py updated.
• Slow integration, local: two new tests against a real service database: tool calls attributed by role, and an MCP client writing through /svc/mcp-email/mcp (the SSE case).
• Results:
  • unit suite 8395 passed, 20 skipped
  • ruff, plugin-api (no break) and uv lock --check pass
  • local slow integration: 11 passed (both /changes tests, consistent mode, gateway trigger tests, register_env_triggers local tests)
  • the two Chromium-based website tests are still left to CI: the browser crashes inside the website-browser container on macOS, with or without this change

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; all three previous findings are addressed and no new actionable issues were found.

Summary

The PR adds /changes to show who may have written each changelog row, plus optional JSONL capture in snapshot_env.

• The gateway names the calls behind environment changelog rows.
• A snapshot step can save attributed environment changes as JSONL.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Tool call or proxied request] --> B[Record starting changelog ID]
  B --> C[Run call or stream response]
  C --> D[Record ending ID and actor]
  D --> E[Join actors to changelog rows]
  E --> F[GET /changes]
  F --> G[Optional snapshot JSONL]

Loading

_{Reviews (2) · Last reviewed commit: "fix(gateway): a result without a window ..." · Reviewed by Greptile}