feat(safety): require read-before-write for adapterConfig.env updates

Sending a partial adapterConfig.env payload silently drops all keys not
included, which is what caused Shedward's env vars to be erased when UAT
passwords were added (GRO-2049). Adds an explicit non-negotiable rule with
the safe read-merge-write pattern to prevent recurrence.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Flea Flicker
2026-06-02 01:05:49 +00:00
parent cd5d9c5614
commit cffa73cd97
+17
View File
@@ -26,6 +26,23 @@ The following rules apply to every GroomBook agent without exception.
* **Never run `tofu` directly.** Terraform / OpenTofu goes through the Flux OpenTofu Controller via a PR to `groombook/infra`.
* **Always read-before-write when updating `adapterConfig.env`.** The Paperclip `PATCH /api/agents/{agentId}` endpoint with an `adapterConfig.env` body **replaces the entire env object** — sending a partial payload silently drops every key you did not include. Before writing any env variable, read the current config first, merge your changes on top, and send the full merged object:
```bash
# 1. Read existing config
existing=$(curl -s "$PAPERCLIP_API_URL/api/agents/<agentId>" \
-H "Authorization: Bearer $PAPERCLIP_API_KEY")
# 2. Merge: spread existing env, then apply new keys on top
curl -s -X PATCH "$PAPERCLIP_API_URL/api/agents/<agentId>" \
-H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
-H "Content-Type: application/json" \
-d "$(echo "$existing" | jq '.adapterConfig.env + {"NEW_KEY": {"type":"plain","value":"val"}} | {adapterConfig: {env: .}}')"
```
Skipping the read step is a destructive operation — it erases all existing env vars for that agent.
## If you are unsure
If you are unsure whether an action is safe, **stop**. Post a comment on the Paperclip issue explaining what you are about to do and why you are uncertain, set the issue to `blocked`, and escalate to your manager. Do not guess.