@kubb/studio 5.3.16 → 5.3.18

package/README.md

@@ -68,6 +68,14 @@ The runtime discovers nothing on its own: the host injects the config loader, th
 own version. That is what lets one runtime serve a CLI running in a developer's project and a
 container running a fixed plugin set.
 
+## Package layers
+
+`src/protocol` defines the shared wire contracts and imports no Studio implementation. `src/operations`
+contains focused work such as pairing, generation, config edits, snapshots, and transport; it may
+import the protocol. `src/runtime` owns connection state and coordinates operations; it may import
+both lower layers. Keep new code in the lowest layer that can own it, with direct internal imports.
+Only `@kubb/studio` and `@kubb/studio/protocol` are public entry points.
+
 ## Hosts and the runtime
 
 Three hosts run this package: `kubb studio`, the `kubblabs/kubb-agent` Docker image, and
@@ -109,14 +117,19 @@ the machine-facing surface, singular because the caller is describing itself. Th
 `/api/agents` is the collection a signed-in user manages in the browser, and the runtime never
 touches it.
 
-| Step       | Call                                              | What it does                                                                       |
-| ---------- | ------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| Register   | `POST /api/agent/connect`                         | Binds the token to this machine with a `machineToken`. A failure here is not fatal |
-| Session    | `POST /api/agent/sessions`                        | Returns `{ url, sessionId, expiresAt }`                                            |
-| Connect    | Configured RPC connector on `url`                 | Attaches the typed `AgentApi`/`StudioApi` RPC session                              |
-| Disconnect | `POST /api/agent/sessions/{sessionId}/disconnect` | Closes the session on a clean shutdown                                             |
+| Step     | Call                                    | What it does                                                                                                                              |
+| -------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Register | `POST /api/agent/connect`               | Binds the token to this machine and process (`machineToken`, `instanceId`), reports `capacity`, and returns `socketUrl`                   |
+| Connect  | Configured RPC connector on `socketUrl` | Opens the process's one socket with the bearer token and `x-kubb-instance-id`, then attaches the typed `AgentApi`/`StudioApi` RPC session |
+
+Every connection attempt registers first, so a reconnect is also how the agent registers again.
+Each heartbeat carries the agent's load. A process keeps one socket, not one per job: Studio
+schedules jobs onto it up to the advertised `maxConcurrent`. Studio's close codes say whether to
+come back: `4001` registers and reconnects, `4002` (another instance took over) and `4003` (the
+agent is too old or was deleted) stay down. A `426` at registration means the agent is too old for
+that Studio.
 
-The runtime reconnects on its own when a session drops, and keeps retrying while Studio is
+The runtime reconnects on its own when the socket drops, and keeps retrying while Studio is
 unreachable. Generation progress is a native Cap'n Web `ReadableStream` on the generation
 capability; durable job status is read through the HTTP job API.
 
@@ -197,6 +210,15 @@ Pass `commit` with a snapshot job, and the finished snapshot carries `changes`:
 changed, and removed since the previous snapshot of the same package on the same agent, and which
 snapshot (and commit) that was. `base` is `null` on the first one.
 
+Pass `baseId` (the `id` another CI agent's runs register under) and the snapshot also carries
+`branchChanges`: the same comparison against that agent's latest snapshot. On a GitHub pull
+request or a GitLab merge request, `kubb studio snapshot` passes the agent its base branch's runs
+use. Elsewhere, pass `--base-id` with the `--id` those runs use.
+
+Runs that share an agent (one pull request, or one branch) must not overlap, since registering it
+again ends the other run's session. Serialize them per ref, such as a GitHub Actions `concurrency`
+group on `github.ref` or a GitLab `resource_group` on `$CI_COMMIT_REF_SLUG`.
+
 A snapshot job packs the tarball on the agent, not on Studio. The agent `PUT`s an empty request to
 a path Studio provides, gets back a redirect to a short-lived storage URL, and uploads the tarball
 there. The storage URL never crosses the RPC socket.