@bongos/core 1.19.709 → 1.19.711

package/docs/api/openapi.json

@@ -29,6 +29,10 @@
       "name": "achievements",
       "description": "Endpoints under `/api/bongos/achievements`."
     },
+    {
+      "name": "agent-runs",
+      "description": "Endpoints under `/api/bongos/agent-runs`."
+    },
     {
       "name": "agents",
       "description": "Endpoints under `/api/bongos/agents`."
@@ -509,6 +513,58 @@
         ]
       }
     },
+    "/agent-runs/{id}": {
+      "get": {
+        "operationId": "get_agent_runs_id",
+        "tags": [
+          "agent-runs"
+        ],
+        "summary": "GET /agent-runs/:id",
+        "description": "GET /agent-runs/:id — COLLECT THE ANSWER TO A FIRE YOU STARTED. OWN RUNS ONLY, enforced in the WHERE clause rather than after the read. The id is a sequential integer primary key, so without this any authenticated builder could walk the ledger and read another builder's held answer — text generated from THEIR free-text question, out of a repo the agent read — plus the github_login in `trigger_ref`. That is the textbook IDOR, and it is worse here than the usual shape because the interesting field is model output derived from someone else's prompt. Filtering in SQL, not in JS, is deliberate: a post-read comparison is one early `return` away from leaking, and it would still have handed the row to `hold.take()` on the way past. A run with a NULL requester (an event-triggered fire — nobody asked for it) is therefore readable by nobody here, which is correct for a route whose job is \"collect MY answer\". An operator's view of the whole ledger is a different surface with a different gate, and it is not built: when it is, it belongs behind `agent.arm`, not behind a widening of this route. See ../lib/answer-hold.js for why the text is held and not stored.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/agents/routes/agents.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetAgentRunsIdResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/agents": {
       "get": {
         "operationId": "get_agents",
@@ -545,6 +601,57 @@
             "builderSession": []
           }
         ]
+      },
+      "post": {
+        "operationId": "post_agents",
+        "tags": [
+          "agents"
+        ],
+        "summary": "POST /agents",
+        "description": "POST /agents — author a definition against the DB, no file edit. It lands DISARMED, always. Creating and arming are separate acts with separate audit lines, and a create that armed would let one call both invent an agent and switch it on — the same reasoning agents-sync rule 4 applies to a commit, applied to an HTTP request.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `agent.author` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/agents/routes/agents.js",
+        "x-permissions": [
+          "agent.author"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": true
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostAgentsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
       }
     },
     "/agents/{name}": {
@@ -597,6 +704,297 @@
             "builderSession": []
           }
         ]
+      },
+      "patch": {
+        "operationId": "patch_agents_name",
+        "tags": [
+          "agents"
+        ],
+        "summary": "PATCH /agents/:name",
+        "description": "PATCH /agents/:name — edit IN PLACE. One row per name, before and after. The patch is merged over the stored row and the WHOLE definition is re-validated (authoring.mergeForValidation says why), against the EDITOR's live rank — which re-stamps author_rank downward if a lower-ranked builder edits, and re-runs the scope wall against that new rank.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `agent.author` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/agents/routes/agents.js",
+        "x-permissions": [
+          "agent.author"
+        ],
+        "parameters": [
+          {
+            "name": "name",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `name`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": true
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PatchAgentsNameResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "delete": {
+        "operationId": "delete_agents_name",
+        "tags": [
+          "agents"
+        ],
+        "summary": "DELETE /agents/:name",
+        "description": "DELETE /agents/:name — only a db-authored definition, and only ever one. The LEDGER is untouched: agents_runs.definition_id is ON DELETE SET NULL and carries a denormalized agent_name, so what this agent spent and did survives the definition it pointed at (the schema header says why).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `agent.author` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/agents/routes/agents.js",
+        "x-permissions": [
+          "agent.author"
+        ],
+        "parameters": [
+          {
+            "name": "name",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `name`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeleteAgentsNameResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/agents/{name}/disable": {
+      "post": {
+        "operationId": "post_agents_name_disable",
+        "tags": [
+          "agents"
+        ],
+        "summary": "POST /agents/:name/disable",
+        "description": "POST /agents/:name/disable — and THIS is what stops dispatch. Two halves, because there are two ways an agent fires. The event dispatch index is partial (`WHERE enabled`), so an event agent switched off stops being selected at all; an on-demand agent has no selection step, so gate.js refuses it at invoke. Off means off on both paths, which is the property this route exists to give an operator.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `agent.arm` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/agents/routes/agents.js",
+        "x-permissions": [
+          "agent.arm"
+        ],
+        "parameters": [
+          {
+            "name": "name",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `name`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostAgentsNameDisableResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/agents/{name}/enable": {
+      "post": {
+        "operationId": "post_agents_name_enable",
+        "tags": [
+          "agents"
+        ],
+        "summary": "POST /agents/:name/enable",
+        "description": "POST /agents/:name/enable — THE OPERATOR ACT. This is the one write that works on a FILE-sourced definition, and it is the whole reason a committed agent can ever run: agents-sync deliberately never arms anything (its rule 4), and carries an operator's `enabled` forward untouched on every later deploy. So arming here is durable, and landing a commit still cannot arm anything. Two refusals it cannot talk its way past, both enforced by the schema as well as here: a flagged definition stays disarmed, and a definition with no author_rank has no authority to act with.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `agent.arm` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/agents/routes/agents.js",
+        "x-permissions": [
+          "agent.arm"
+        ],
+        "parameters": [
+          {
+            "name": "name",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `name`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostAgentsNameEnableResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/agents/{name}/invoke": {
+      "post": {
+        "operationId": "post_agents_name_invoke",
+        "tags": [
+          "agents"
+        ],
+        "summary": "POST /agents/:name/invoke",
+        "description": "POST /agents/:name/invoke — fire an on-demand agent. 202, never 200. A fire takes 60-120 seconds and costs about a dollar, which is past the edge proxy's patience — so the ledger row IS the response and the run continues behind it. Collect the answer from GET /agent-runs/:id. SELF-GATED at requireBuilder, deliberately, matching the reads: which agents exist at all is an operator decision, and a v1 agent is hard-read-only. The thing that reasoning does NOT bound is SPEND, so a per-builder ceiling does (../lib/fire-budget.js). It is a blast radius, not a budget: the real accounting is agents_runs.cost_usd through the shared LLM cost cache.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/agents/routes/agents.js",
+        "parameters": [
+          {
+            "name": "name",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `name`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostAgentsNameInvokeRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostAgentsNameInvokeResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
       }
     },
     "/analytics/builder/{id}": {
@@ -16689,6 +17087,19 @@
         },
         "description": "The inner error object carried by every non-2xx response."
       },
+      "DeleteAgentsNameResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "deleted": {}
+        },
+        "required": [
+          "ok",
+          "deleted"
+        ]
+      },
       "DeleteBoxSshKeyIdResponse": {
         "type": "object",
         "properties": {
@@ -16870,6 +17281,19 @@
           "achievements"
         ]
       },
+      "GetAgentRunsIdResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "run": {}
+        },
+        "required": [
+          "ok",
+          "run"
+        ]
+      },
       "GetAgentsNameResponse": {
         "type": "object",
         "properties": {
@@ -18515,6 +18939,19 @@
           "request"
         ]
       },
+      "PatchAgentsNameResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "agent": {}
+        },
+        "required": [
+          "ok",
+          "agent"
+        ]
+      },
       "PatchBoxesBuilderIdBlockRequest": {
         "type": "object",
         "properties": {
@@ -19239,6 +19676,72 @@
           "ok"
         ]
       },
+      "PostAgentsNameDisableResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "agent": {}
+        },
+        "required": [
+          "ok",
+          "agent"
+        ]
+      },
+      "PostAgentsNameEnableResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "agent": {}
+        },
+        "required": [
+          "ok",
+          "agent"
+        ]
+      },
+      "PostAgentsNameInvokeRequest": {
+        "type": "object",
+        "properties": {
+          "input": {
+            "type": "string",
+            "maxLength": 8192
+          }
+        },
+        "additionalProperties": false
+      },
+      "PostAgentsNameInvokeResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "run_id": {},
+          "poll": {},
+          "message": {}
+        },
+        "required": [
+          "ok",
+          "run_id",
+          "poll",
+          "message"
+        ]
+      },
+      "PostAgentsResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "agent": {}
+        },
+        "required": [
+          "ok",
+          "agent"
+        ]
+      },
       "PostAuthAppPairApproveRequest": {
         "type": "object",
         "properties": {
@@ -23116,9 +23619,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 365,
-  "x-schema-count": 403,
+  "x-endpoint-count": 372,
+  "x-schema-count": 411,
   "x-undocumented-bodies": 9,
-  "x-response-schemas": 272,
+  "x-response-schemas": 279,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 365 endpoints across 59 route files.
+> **Generated from the live route files** — the route file is authoritative. 372 endpoints across 59 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -23,12 +23,24 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 |---|---|---|---|---|
 | GET | `/api/bongos/achievements` | `any-builder` | — | All seeded achievements — lets /builders render locked + unlocked side by side. |
 
-## `agents` (2)
+## `agent-runs` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/agent-runs/:id` | `any-builder` | — | GET /agent-runs/:id — COLLECT THE ANSWER TO A FIRE YOU STARTED. |
+
+## `agents` (8)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/agents` | `any-builder` | — | GET /agents — the whole registry. |
+| POST | `/api/bongos/agents` | `metic+archon` | validated | POST /agents — author a definition against the DB, no file edit. |
 | GET | `/api/bongos/agents/:name` | `any-builder` | — | GET /agents/:name — one definition, persona included. |
+| PATCH | `/api/bongos/agents/:name` | `metic+archon` | validated | PATCH /agents/:name — edit IN PLACE. |
+| DELETE | `/api/bongos/agents/:name` | `metic+archon` | — | DELETE /agents/:name — only a db-authored definition, and only ever one. |
+| POST | `/api/bongos/agents/:name/disable` | `metic+archon` | — | POST /agents/:name/disable — and THIS is what stops dispatch. |
+| POST | `/api/bongos/agents/:name/enable` | `metic+archon` | — | POST /agents/:name/enable — THE OPERATOR ACT. |
+| POST | `/api/bongos/agents/:name/invoke` | `any-builder` | `input` | POST /agents/:name/invoke — fire an on-demand agent. |
 
 ## `analytics` (1)
 

package/docs/module-api-changelog.md

@@ -1877,5 +1877,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.707 with no explicit bump. run 34742245823. (task 1002620)
   1.19.709 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.708 with no explicit bump. run 34743928060. (task 1002620)
+  1.19.710 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.709 with no explicit bump. run 34744369035. (task 1002620)
+  1.19.711 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.710 with no explicit bump. run 34744940181. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/ops-gotchas.md

@@ -25,6 +25,20 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 - **Why it bites:** The `pg` library's defaults assume a standard TCP+password setup, which is the most common configuration but not the cheapest one for a single-machine deploy. Peer auth is more secure and frictionless once you know the socket path. The error message points at SASL, not at the host setting, which buries the real cause.
 - **Where this lives in the codebase:** [`src/db.js`](../../src/db.js) has the explicit socket host.
 
+### Re-provisioning an EXISTING instance moves its `HOME`, orphaning any stored builder secrets
+
+- **Symptom:** after a re-provision, an instance that had builder API keys stored can no longer decrypt them. Nothing errors at startup — the instance comes up healthy and simply behaves as though no key was ever saved.
+- **Root cause:** task [1003369](https://cloudbongos.com/builders#/task/1003369) ([ADR 0281](../adr/<redacted>.md)) gives each instance its own unix account with `HOME=/var/lib/bongos-<slug>`. [`src/bongos/secret-box.js`](../../src/bongos/secret-box.js) keeps its master key at `~/.config/<configDir>/builder-secret.key`, so the key an instance wrote under the OLD shared home (`/home/lars/.config/…`) is no longer on its `HOME` path. `provisionMasterKey()` finds nothing, mints a fresh key, and every previously encrypted secret is now undecryptable ciphertext.
+- **Who this hits:** only a **re-provision of an instance that has already stored secrets**. A fresh standup has nothing to lose, and an instance whose `web.env` sets `BUILDER_SECRET_KEY` is unaffected — that env wins over the file.
+- **Fix (before the re-provision, one command as root):**
+  ```bash
+  install -D -o bongos-<slug> -g bongos-<slug> -m 600 \
+    /home/lars/.config/<configDir>/builder-secret.key \
+    /var/lib/bongos-<slug>/.config/<configDir>/builder-secret.key
+  ```
+  `<configDir>` is the instance’s `branding.configDir` (vanilla: `cloudbongos`). Do it **first** — `provisionMasterKey()` writes with the `wx` flag and refuses to clobber, so a key placed after the instance has already minted its own will not be picked up.
+- **Why it bites:** the failure is silent on both ends. The old key is not deleted, the new one is valid, and the only visible symptom is secrets that quietly stopped working.
+
 ---
 
 ## Colyseus