loopctl-mcp-server 2.93.0 → 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. |
 

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:
@@ -8290,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/package.json

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