loopctl-mcp-server 2.92.1 → 2.94.0

package/README.md

@@ -220,6 +220,7 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 | `contract_story` | Agent acknowledges a story's acceptance criteria. Transitions pending -> contracted. |
 | `claim_story` | Agent claims a contracted story with pessimistic locking. Transitions contracted -> assigned. On a loopctl with claim leases the result leads with the claim's `claim_epoch` and `claimed_until`; keep the epoch for `renew_story_claim`. Both are absent on an older server. |
 | `renew_story_claim` | Renew your claim's lease (`POST /stories/:id/renew-claim`, agent key). A claim not renewed before `claimed_until` (default 24 hours, `STORY_CLAIM_LEASE_SECONDS`) is released back to `pending` under you, so renew well inside it on any story held longer. Required: `story_id`, `claim_epoch` (from the claim). Refusals pass through: 400 epoch missing or malformed, 422 `not_claimed`, 409 `stale_claim_epoch` (the claim has ended: stop working it), 409 `not_claimant`. Needs a loopctl server with claim leases. |
+| `escalate_story` | Park a story you hold for a HUMAN and stop (`POST /stories/:id/escalate`, agent key). This is what an unattended session calls INSTEAD of asking a question — a headless run has no way to ask, so escalating is the affordance. Use it when the request contradicts an existing story, KB decision or documented behaviour, when it inverts or removes behaviour a previous story deliberately added, when it is a workflow change rather than a defect fix, or when it needs a business call — not for an ordinary blocker. ONE-WAY from your side: only a human moves the story off `escalated`, so on success STOP and report. Required: `story_id`, `claim_epoch`, `reason` (verbatim, treated as untrusted data, length capped by the server in codepoints — a 400 names the bound); optional `payload` object. Idempotent under the same epoch. Refusals pass through: 409 `stale_claim_epoch`, 409 `not_claimant`, 404 `unknown_story_stage`, 400 for a malformed epoch or reason. An orchestrator or user key is 403'd on purpose. |
 | `start_story` | Agent starts work on a claimed story. Transitions assigned -> implementing. |
 | `request_review` | Agent signals implementation is complete and ready for review. |
 
@@ -471,10 +472,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

@@ -46,6 +46,7 @@ import { createHandoff } from "./lib/handoff.js";
 import { readPayloadFile } from "./lib/payload-path.js";
 import { enrollRunner, listRunners, revokeRunner, runnerPool } from "./lib/runners.js";
 import { claimLeaseNotice, renewStoryClaim as renewStoryClaimRequest } from "./lib/claim-lease.js";
+import { escalateStory as escalateStoryRequest, escalationNotice } from "./lib/escalation.js";
 
 // Single source of truth for the server version: the package.json this file
 // ships with (npm always includes package.json in the published tarball).
@@ -1151,6 +1152,15 @@ async function renewStoryClaim(args) {
   return withClaimLeaseNotice(await renewStoryClaimRequest(args, { apiCall }));
 }
 
+// #803: escalation leads with a STOP line. A session that escalates and keeps working is
+// the failure the affordance exists to prevent, and the JSON body alone does not say so.
+async function escalateStory(args) {
+  const result = await escalateStoryRequest(args, { apiCall });
+  const notice = escalationNotice(result);
+  if (!notice) return toContent(result);
+  return { content: [{ type: "text", text: notice }, ...toContent(result).content] };
+}
+
 async function startStory({ story_id, capability }) {
   // Cache first, then DELIVERY of the token claim already minted, then recovery
   // (which mints a fresh one). Delivery also covers a legacy env-var key, whose
@@ -4085,6 +4095,56 @@ const TOOLS = [
       required: ["story_id", "claim_epoch"],
     },
   },
+  {
+    name: "escalate_story",
+    description:
+      "Park a story you hold for a HUMAN to decide, and stop (POST /api/v1/stories/:id/escalate). " +
+      "This is what you call instead of asking a question: an unattended session has no way to " +
+      "ask, so escalating is the affordance. Use it when the request contradicts an existing " +
+      "story, KB decision or documented behaviour; when it inverts or removes behaviour a " +
+      "previous story deliberately added; when it is a workflow change rather than a defect fix; " +
+      "or when it needs a business call. Do NOT use it for an ordinary blocker you can work " +
+      "through. It is ONE-WAY from your side: only a human moves the story off `escalated`, so " +
+      "after a success, stop working the story and report that you escalated and why. Uses the " +
+      "AGENT key, the same key as claim_story; an orchestrator or user key is 403'd on purpose. " +
+      "IDEMPOTENT: repeating it under the same claim_epoch returns the same stage row and writes " +
+      "nothing twice. Refusals pass through: 409 stale_claim_epoch (the claim has ENDED, stop " +
+      "working it), 409 not_claimant (your key's agent is not the story's), 404 " +
+      "unknown_story_stage (the story is not in the delivery loop), 400 for a missing or " +
+      "malformed claim_epoch or reason.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        story_id: {
+          type: "string",
+          description: "The UUID of the story you hold.",
+        },
+        claim_epoch: {
+          type: "integer",
+          minimum: 0,
+          description: "The claim_epoch your claim_story result returned.",
+        },
+        reason: {
+          type: "string",
+          minLength: 1,
+          description:
+            "What a human has to decide, in your own words. Recorded verbatim and treated as " +
+            "untrusted data everywhere it is read. The SERVER caps its length, in codepoints " +
+            "(what Postgres counts, not graphemes) — no bound is repeated here, because a " +
+            "number baked into a published npm package goes stale against the server that " +
+            "enforces it. Over the cap is a 400 naming the bound.",
+        },
+        payload: {
+          type: "object",
+          additionalProperties: true,
+          description:
+            "Optional structured detail — the story or KB article it contradicts, the two " +
+            "options you are between. Recorded on the stage event; at most 8000 bytes encoded.",
+        },
+      },
+      required: ["story_id", "claim_epoch", "reason"],
+    },
+  },
   {
     name: "start_story",
     description:
@@ -7492,6 +7552,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 +7598,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 " +
@@ -8279,6 +8350,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
     case "renew_story_claim":
       return await renewStoryClaim(args);
+    case "escalate_story":
+      return await escalateStory(args);
 
     case "start_story":
       return await startStory(args);

package/lib/escalation.js

@@ -0,0 +1,69 @@
+/**
+ * Story escalation (loopctl #803, design §8; MCP side under #809).
+ *
+ * `escalate_story` is the POSITIVE AFFORDANCE an unattended session has instead of a
+ * question. A headless run has no AskUserQuestion at all, and nothing fires when the model
+ * wanted to ask — no tool call is attempted, so no hook sees anything — which is why the
+ * session must be able to DO something rather than be detected wanting to.
+ *
+ * It is one-way from the session's side: the story parks at the `escalated` delivery stage
+ * and only a HUMAN principal moves it off. So the result leads with a line saying to STOP,
+ * because a session that escalates and keeps working is the failure this exists to prevent
+ * and a bare JSON body does not say so.
+ *
+ * SINGLE SOURCE OF TRUTH. index.js injects `apiCall`; the unit suite runs this code with a
+ * recording fake. The KEY is selected here, from the injected env, so the key an escalation
+ * travels on is testable behaviour rather than a source pattern — and it must be the AGENT
+ * key, because the endpoint is `exact_role: :agent`: the human key that RESOLVES an
+ * escalation is 403'd, which is the separation the route exists inside.
+ *
+ * Only `story_id` and a non-empty `reason` are validated client-side. Everything else is the
+ * server's judgement and passes through unchanged: 409 stale_claim_epoch (the claim ended —
+ * stop working it), 409 not_claimant, 404 unknown_story_stage, 400 for a malformed epoch.
+ */
+
+export function escalatePath(storyId) {
+  return `/api/v1/stories/${encodeURIComponent(storyId)}/escalate`;
+}
+
+/**
+ * `POST /api/v1/stories/:id/escalate {claim_epoch, reason, payload?}` on the AGENT key.
+ * `claim_epoch` is forwarded exactly as given, and `payload` is omitted when absent rather
+ * than sent as null.
+ */
+export async function escalateStory(
+  { story_id, claim_epoch, reason, payload } = {},
+  { apiCall, env = process.env } = {},
+) {
+  if (typeof story_id !== "string" || story_id.trim() === "") {
+    return { error: true, status: 0, body: "`story_id` is required." };
+  }
+  if (typeof reason !== "string" || reason.trim() === "") {
+    return {
+      error: true,
+      status: 0,
+      body: "`reason` is required: say what a human has to decide, in your own words.",
+    };
+  }
+
+  const body = { claim_epoch, reason };
+  if (payload !== undefined && payload !== null) body.payload = payload;
+
+  return apiCall("POST", escalatePath(story_id), body, env.LOOPCTL_AGENT_KEY);
+}
+
+/**
+ * The line that leads a successful escalation, or null on a refusal. It says STOP, because
+ * the whole point of the call is that the session hands the decision over and does no more
+ * work on the story.
+ */
+export function escalationNotice(result) {
+  const stage = result && result.error !== true ? result.stage : null;
+  if (!stage || stage.stage !== "escalated") return null;
+
+  return (
+    "ESCALATED: this story is parked for a human and only a human moves it off. " +
+    "STOP working it now — do not implement, do not open a PR, do not pick the decision " +
+    "yourself. Report that you escalated and why."
+  );
+}

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.94.0",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",