Merge pull request 'feat(safety): require read-before-write for adapterConfig.env updates' (#12 ) from fix/gro-2049-adapter-env-preservation into main

Reviewed-on: #12
feat(safety): require read-before-write for adapterConfig.env updates
2026-06-02 01:07:28 +00:00 · 2026-06-02 01:05:49 +00:00
1 changed files with 17 additions and 0 deletions
@@ -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.