loopctl-mcp-server 2.92.1 → 2.93.0

package/README.md

@@ -471,10 +471,10 @@ Enroll the dev machines that run the agent delivery loop, and see which are conn
 
 | Tool | Description |
 |---|---|
-| `runner_enroll` | Enroll this machine as a runner (`POST /api/v1/runners`). Required: `name` (the machine name the runner declares when it joins) and `token_file` (absolute, or starting with `~/`). The credential is written to `token_file` with mode 0600 and is **never returned**: the result is only `{ runner: {id, name, inserted_at}, token_file }`, because a tool result lands in the transcript and the token lets its holder join as that machine. The file is created exclusively, so an existing path (or a symlink there) is refused before anything is enrolled; missing parent directories are created 0700. If the token cannot be written after enrollment, the runner is revoked before the error returns. Only a 4xx is treated as a refusal: any other failure (timeout, 5xx, a 2xx that did not parse) may have enrolled the runner, so its response body is never echoed, the runner is revoked when the response proves its id, and otherwise the error points at `runner_list` and `runner_revoke`. 422 (name malformed or taken) and 403 (`custody_tier_required`, `api_key_mint_forbidden`) pass through with their code. |
+| `runner_enroll` | Enroll this machine as a runner (`POST /api/v1/runners`). Required: `name` (the machine name the runner declares when it joins) and `token_file` (absolute, or starting with `~/`). Optional: `max_sessions` (1..64, default 2) — how many dispatches loopctl keeps in flight on this machine at once; the tenant's total across its runners is capped separately by the server. The credential is written to `token_file` with mode 0600 and is **never returned**: the result is only `{ runner: {id, name, inserted_at}, token_file }`, because a tool result lands in the transcript and the token lets its holder join as that machine. The file is created exclusively, so an existing path (or a symlink there) is refused before anything is enrolled; missing parent directories are created 0700. If the token cannot be written after enrollment, the runner is revoked before the error returns. Only a 4xx is treated as a refusal: any other failure (timeout, 5xx, a 2xx that did not parse) may have enrolled the runner, so its response body is never echoed, the runner is revoked when the response proves its id, and otherwise the error points at `runner_list` and `runner_revoke`. 422 (name malformed or taken) and 403 (`custody_tier_required`, `api_key_mint_forbidden`) pass through with their code. |
 | `runner_list` | List enrolled runners (`GET /api/v1/runners`). Optional: `include_revoked`. Enrollment only; connection state is `runner_pool`. |
 | `runner_revoke` | Revoke a runner (`DELETE /api/v1/runners/:id`): its credential stops authenticating and its live socket is disconnected. The undo for `runner_enroll`. Idempotent. Required: `id`. |
-| `runner_pool` | The tenant's connected runners from Presence (`GET /api/v1/runners/pool`): per machine name, `runner_id`, `joined_at`, `in_flight`, `draining`, `max_sessions`, the latest `sample`, `live_sockets` (above 1 means more than one process holds the credential), and the `node` and `machine_id` (Fly Machine) holding the socket. Presence converges only within a cluster. |
+| `runner_pool` | The tenant's connected runners from Presence (`GET /api/v1/runners/pool`): per machine name, `runner_id`, `joined_at`, `draining`, the latest `sample`, `live_sockets` (above 1 means more than one process holds the credential), and the `node` and `machine_id` (Fly Machine) holding the socket. `in_flight` and `max_sessions` are the capacity loopctl holds in Postgres — what dispatch reserves against — and are null only for a runner revoked while its socket drains; `reported_in_flight` and `reported_max_sessions` are the runner's own last report, a hint. Presence converges only within a cluster. |
 
 ### Dispatch & Chain of Custody (v2) Tools
 

package/index.js

@@ -7492,6 +7492,14 @@ const TOOLS = [
           description:
             "Absolute path, or one starting with ~/, for the token file. Must not exist yet.",
         },
+        max_sessions: {
+          type: "integer",
+          minimum: 1,
+          maximum: 64,
+          description:
+            "How many dispatches loopctl keeps in flight on this machine at once (default 2). " +
+            "The tenant's total across all its runners is capped separately by the server.",
+        },
       },
       required: ["name", "token_file"],
     },
@@ -7530,8 +7538,11 @@ const TOOLS = [
     name: "runner_pool",
     description:
       "The tenant's CONNECTED runners, read from Presence (GET /api/v1/runners/pool): per machine " +
-      "name, runner_id, joined_at, in_flight, draining, max_sessions, the latest health sample, " +
-      "live_sockets, and the node and machine_id (Fly Machine) holding the socket. live_sockets " +
+      "name, runner_id, joined_at, draining, the latest health sample, live_sockets, and the node " +
+      "and machine_id (Fly Machine) holding the socket. in_flight and max_sessions are the " +
+      "CAPACITY loopctl holds in Postgres — the slots dispatch reserves against — and are null " +
+      "only for a runner revoked while its socket drains; reported_in_flight and " +
+      "reported_max_sessions are what the runner itself last reported, a hint. live_sockets " +
       "above 1 means more than one process holds that runner's credential. A killed runner " +
       "disappears once its socket closes. Presence converges only " +
       "within a cluster, so on an unclustered multi-node deployment a runner on another node is " +

package/lib/runners.js

@@ -65,12 +65,18 @@ export function expandHome(p, homedir = os.homedir()) {
 }
 
 /**
- * `POST /api/v1/runners {name}`, with the returned token written to `token_file` and
- * never returned. Resolves to `{ runner: {id, name, inserted_at}, token_file }` or an
+ * `POST /api/v1/runners {name, max_sessions?}`, with the returned token written to
+ * `token_file` and never returned. Resolves to
+ * `{ runner: {id, name, max_sessions, inserted_at}, token_file }` or an
  * `{ error: true, status, body }` shape. It never throws.
+ *
+ * `max_sessions` is how many dispatches loopctl will keep in flight on this machine at
+ * once (loopctl #803). It is sent ONLY when given, so the server's own default applies
+ * otherwise, and the server refuses one out of range with a 422 that passes straight
+ * through — this does not second-guess the bound.
  */
 export async function enrollRunner(
-  { name, token_file } = {},
+  { name, token_file, max_sessions } = {},
   { userKey, apiCall, fs = defaultFs, homedir = os.homedir() } = {},
 ) {
   if (!userKey) return refuse(MISSING_USER_KEY);
@@ -115,7 +121,8 @@ export async function enrollRunner(
 
   let result;
   try {
-    result = await apiCall("POST", RUNNERS_PATH, { name });
+    const body = max_sessions === undefined ? { name } : { name, max_sessions };
+    result = await apiCall("POST", RUNNERS_PATH, body);
   } catch {
     result = { error: true, status: 0, body: "Enrollment request failed." };
   }
@@ -153,8 +160,15 @@ export async function enrollRunner(
     );
   }
 
+  // `max_sessions` only when the server sent one, so a server without loopctl #803 returns
+  // exactly the shape it always did rather than a key that is always undefined.
   return {
-    runner: { id: runner.id, name: runner.name, inserted_at: runner.inserted_at },
+    runner: {
+      id: runner.id,
+      name: runner.name,
+      ...(runner.max_sessions === undefined ? {} : { max_sessions: runner.max_sessions }),
+      inserted_at: runner.inserted_at,
+    },
     token_file: tokenPath,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.92.1",
+  "version": "2.93.0",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",