@rackbops/plugin-mcp 0.3.2 → 0.4.0

package/README.md

@@ -4,9 +4,11 @@ The bridge plugin for the Discord delivery MCP ([`Rackbops/discord-mcp`](https:/
 [Rackbops/Tooling#742](https://github.com/Rackbops/Tooling/issues/742)). It implements the service
 side of that repo's `docs/bridge-protocol.md` under `/mcp/` on the bot's own HTTP listener
 (rackbops-discord-bot's host-owned router, ADR-0007) -- `GET /capabilities`,
-`POST /deliveries`, `GET /deliveries/{request_id}` and `GET /recipients` -- so the MCP service can
-hand it a message and get exactly one Discord post, DM or edit out of it, however many times it
-retries. It also owns Discord-side agent identity ([Rackbops/Tooling#743](https://github.com/Rackbops/Tooling/issues/743)):
+`POST /deliveries`, `GET /deliveries/{request_id}`, `GET /recipients` and
+`GET /recipients/{user_id}` -- so the MCP service can
+hand it a message and get one Discord post, DM or edit out of it: a retry of a request that is
+delivered or in flight never delivers again (a retry of a failed or unknown one, and the restart
+re-drive, deliver at least once -- see below). It also owns Discord-side agent identity ([Rackbops/Tooling#743](https://github.com/Rackbops/Tooling/issues/743)):
 the `/agent` slash command, and `POST /pair/redeem` + `GET /registration/{user_id}` under the same
 `/mcp/` path.
 
@@ -18,8 +20,13 @@ command's own replies name whichever form the user invoked.
 
 - Accepts a delivery request, answers `202` immediately, and delivers to Discord in the background.
 - Keeps one state file per `request_id` (`pending` -> `delivered`/`failed`, or `unknown` after a bot
-  restart mid-delivery) so a retry with the same `request_id` never delivers twice.
-- A tick re-drives any delivery a restart left `unknown`, and prunes records older than 8 days.
+  restart mid-delivery) so a retry with the same `request_id` of a `delivered` or `pending` request
+  never delivers again.
+- A retry of a `failed` or `unknown` request resets it to `pending` and delivers again. A tick
+  re-drives any delivery a restart left `unknown`, and prunes records older than 8
+  days. Delivery is therefore at-least-once: a restart between the Discord call and the state
+  write can post a second copy. A state write that fails without a restart does not: the outcome is
+  held in memory, answered from there, and the tick retries the write alone (that memory is lost on a restart).
 - `kind: "post"` goes through `host.post` (or `host.announce` when the host predates it); `kind: "dm"`
   goes through `host.dm`, to a registered user only; `kind: "edit"` goes through `host.edit`, applied
   against the stored delivery `message_ref` names. `GET /capabilities` reports `dm`/`edit` as `true`
@@ -84,6 +91,17 @@ most 100, each `display_name` truncated to 100 characters (same bearer auth; any
 200: {"items":[]}
 ```
 
+`GET /recipients/{user_id}` -- one registered user, in the same shape as a `GET /recipients` item
+and with the same display-name truncation, but with no cap: a user registered after the first 100
+still finds their own entry here. `user_id` must be a snowflake (`[1-9][0-9]{16,19}`); a malformed
+one falls through to the generic `404 {"error":"not found"}`. Same bearer auth; any other method is
+`405`:
+
+```
+200: {"user_id":"123456789012345678","display_name":"Roshne"}
+404: {"error":"not registered"}
+```
+
 `GET /capabilities` now reflects the host's real `dm`/`edit` support:
 
 ```
@@ -124,7 +142,7 @@ stale `generation` for a user has been revoked and re-paired since, not merely r
 
 | Key | Required | Secret | What it does |
 |---|---|---|---|
-| `MCP_BRIDGE_TOKEN` | No | Yes | The bearer token the MCP service must present. Unset = every request gets `503 {"error":"bridge not configured"}`. At least 256 bits, base64url -- generate one with e.g. `openssl rand -base64 32 \| tr -d '=' \| tr '/+' '_-'`. |
+| `MCP_BRIDGE_TOKEN` | No | Yes | The bearer token the MCP service must present. Unset = every request gets `503 {"error":"bridge not configured"}`. At least 43 printable ASCII characters (the manifest `format` checks only that, not entropy or alphabet); 256 bits of base64url is recommended -- generate one with e.g. `openssl rand -base64 32 \| tr -d '=' \| tr '/+' '_-'`. |
 
 ## Destinations
 
@@ -155,5 +173,5 @@ that verifies.
 
 `docs/bridge-protocol.md` in [`Rackbops/discord-mcp`](https://github.com/Rackbops/discord-mcp) is the
 protocol this plugin implements; where this README and that document ever disagree, the protocol
-document wins (this plugin is the implementation, not the source of truth). See `CONTEXT.md` in this
-repo for the file-by-file breakdown and the state-machine gotchas.
+document wins (this plugin is the implementation, not the source of truth). See the header comment of
+each file under `src/` for the file-by-file breakdown and the state-machine gotchas.

package/dist/plugin.js

@@ -257,13 +257,46 @@ function toWireState(stored) {
 }
 function recipientsResponse(entries) {
   const sorted = [...entries].sort((a, b) => a.registeredAt.localeCompare(b.registeredAt) || a.userId.localeCompare(b.userId));
-  return {
-    items: sorted.slice(0, RECIPIENTS_MAX).map((e) => ({ user_id: e.userId, display_name: e.displayName.slice(0, DISPLAY_NAME_MAX) }))
-  };
+  return { items: sorted.slice(0, RECIPIENTS_MAX).map(recipientResponse) };
+}
+function recipientResponse(entry) {
+  return { user_id: entry.userId, display_name: entry.displayName.slice(0, DISPLAY_NAME_MAX) };
 }
 
 // plugins/mcp/src/drain.ts
+function describeError(err) {
+  if (!(err instanceof Error))
+    return "non-Error rejection";
+  const { status, code } = err;
+  const parts = [err.name];
+  if (typeof status === "number")
+    parts.push(`status ${status}`);
+  if (typeof code === "number" || typeof code === "string")
+    parts.push(`code ${code}`);
+  return parts.join(", ");
+}
 var RECIPIENT_UNREACHABLE_MESSAGE = "recipient cannot be messaged";
+var UNPERSISTED_MAX_AGE_MS = 8 * 24 * 60 * 60 * 1000;
+function createUnpersistedOutcomes() {
+  const held = new Map;
+  return {
+    get: (requestId) => held.get(requestId),
+    set: (requestId, outcome) => void held.set(requestId, outcome),
+    delete: (requestId) => void held.delete(requestId),
+    entries: () => [...held.entries()],
+    prune(now) {
+      const cutoff = now().getTime() - UNPERSISTED_MAX_AGE_MS;
+      const dropped = [];
+      for (const [requestId, outcome] of held) {
+        if (new Date(outcome.createdAt).getTime() <= cutoff) {
+          held.delete(requestId);
+          dropped.push(requestId);
+        }
+      }
+      return dropped;
+    }
+  };
+}
 function createEditQueue() {
   const chains = new Map;
   return {
@@ -302,10 +335,14 @@ async function attemptEdit(deps, requestId, target, body) {
     try {
       await deps.host.edit(delivered.delivery, body);
     } catch (err) {
-      deps.log.error(`edit ${requestId} (of ${messageRef}) failed`, err);
+      deps.log.error(`edit ${requestId} (of ${messageRef}) failed: ${describeError(err)}`);
       return { state: "failed", code: "UPSTREAM_UNAVAILABLE" };
     }
-    await deps.store.recordEditSeq(messageRef, seq);
+    try {
+      await deps.store.recordEditSeq(messageRef, seq);
+    } catch (err) {
+      deps.log.error(`recording edit seq ${seq} on ${messageRef} failed: ${describeError(err)}`);
+    }
     return { state: "delivered", messageRef: delivered.messageRef, url: delivered.url, delivery: delivered.delivery, applied: true };
   });
 }
@@ -329,7 +366,7 @@ async function attemptDm(deps, requestId, target, body) {
     if (err instanceof Error && err.message === RECIPIENT_UNREACHABLE_MESSAGE) {
       return { state: "failed", code: "RECIPIENT_UNREACHABLE" };
     }
-    deps.log.error(`delivery ${requestId} failed`, err);
+    deps.log.error(`delivery ${requestId} failed: ${describeError(err)}`);
     return { state: "failed", code: "UPSTREAM_UNAVAILABLE" };
   }
 }
@@ -353,7 +390,7 @@ async function attemptDelivery(deps, requestId, entry) {
       const url = `https://discord.com/channels/${delivery.guildId ?? "@me"}/${delivery.channelId}/${delivery.messageId}`;
       return { state: "delivered", messageRef: requestId, url, delivery };
     } catch (err) {
-      log.error(`delivery ${requestId} failed`, err);
+      log.error(`delivery ${requestId} failed: ${describeError(err)}`);
       return { state: "failed", code: "UPSTREAM_UNAVAILABLE" };
     }
   }
@@ -364,7 +401,7 @@ async function attemptDelivery(deps, requestId, entry) {
     await host.announce(body.content ?? "", target.destination);
     return { state: "delivered", messageRef: null, url: null, delivery: null };
   } catch (err) {
-    log.error(`delivery ${requestId} failed`, err);
+    log.error(`delivery ${requestId} failed: ${describeError(err)}`);
     return { state: "failed", code: "UPSTREAM_UNAVAILABLE" };
   }
 }
@@ -401,7 +438,13 @@ async function drainAndPersist(deps, requestId, entry) {
     delivery: outcome.delivery,
     ...outcome.applied !== undefined ? { applied: outcome.applied } : {}
   } : { ...entry, state: "failed", code: outcome.code };
-  await deps.store.set(requestId, next);
+  try {
+    await deps.store.set(requestId, next);
+  } catch (err) {
+    deps.unpersisted.set(requestId, next);
+    throw err;
+  }
+  deps.unpersisted.delete(requestId);
 }
 
 // plugins/mcp/src/http.ts
@@ -411,6 +454,7 @@ function json(status, body) {
 async function startDrain(deps, requestId, entry) {
   if (!deps.drainLock.tryStart(requestId))
     return false;
+  deps.unpersisted.delete(requestId);
   try {
     await deps.store.set(requestId, entry);
   } catch (err) {
@@ -449,7 +493,9 @@ async function handleCreateDelivery(request, deps) {
     }
     return json(202, { state: toWireState(value), existing });
   }
-  const { value, existing } = await deps.store.reserve(requestId, kind, target, body, deps.now);
+  const reserved = await deps.store.reserve(requestId, kind, target, body, deps.now);
+  const { existing } = reserved;
+  const value = (existing ? deps.unpersisted.get(requestId) : undefined) ?? reserved.value;
   if (!existing) {
     await startDrain(deps, requestId, value);
     return json(202, { state: toWireState(value), existing });
@@ -465,10 +511,10 @@ async function handleCreateDelivery(request, deps) {
     createdAt: value.createdAt
   };
   const started = await startDrain(deps, requestId, reset);
-  return json(202, { state: toWireState(started ? reset : value), existing });
+  return json(202, { state: toWireState(started || value.state === "failed" ? reset : value), existing });
 }
 async function handleGetDelivery(requestId, deps) {
-  const value = await deps.store.get(requestId);
+  const value = deps.unpersisted.get(requestId) ?? await deps.store.get(requestId);
   if (value === undefined)
     return json(404, { error: "unknown request_id" });
   return json(200, toWireState(value));
@@ -504,8 +550,15 @@ async function handleGetRecipients(deps) {
   const entries = await deps.registry.listRecipients();
   return json(200, recipientsResponse(entries));
 }
+async function handleGetRecipient(userId, deps) {
+  const entry = await deps.registry.recipientOf(userId);
+  if (entry === undefined)
+    return json(404, { error: "not registered" });
+  return json(200, recipientResponse(entry));
+}
 var DELIVERY_ID_RE = /^\/deliveries\/([0-9a-f]{64})$/;
 var REGISTRATION_ID_RE = /^\/registration\/([1-9][0-9]{16,19})$/;
+var RECIPIENT_ID_RE = /^\/recipients\/([1-9][0-9]{16,19})$/;
 async function handleMcpHttp(request, info, deps) {
   if (deps.token === undefined)
     return json(503, { error: "bridge not configured" });
@@ -548,6 +601,12 @@ async function handleMcpHttp(request, info, deps) {
       return json(405, { error: "method not allowed" });
     return handleGetRecipients(deps);
   }
+  const recipientMatch = RECIPIENT_ID_RE.exec(info.path);
+  if (recipientMatch) {
+    if (request.method !== "GET")
+      return json(405, { error: "method not allowed" });
+    return handleGetRecipient(recipientMatch[1], deps);
+  }
   return json(404, { error: "not found" });
 }
 
@@ -557,6 +616,20 @@ import { join } from "path";
 function freshRegistry() {
   return { users: {} };
 }
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isEntry(value) {
+  if (!isPlainObject(value))
+    return false;
+  const { generation, displayName, registeredAt, codes } = value;
+  return typeof generation === "string" && typeof displayName === "string" && typeof registeredAt === "string" && Array.isArray(codes) && codes.every((c) => isPlainObject(c) && typeof c.hash === "string" && typeof c.expiresAt === "string");
+}
+function normalizeRegistry(raw) {
+  if (!isPlainObject(raw) || !isPlainObject(raw.users))
+    return freshRegistry();
+  return { users: Object.fromEntries(Object.entries(raw.users).filter((pair) => isEntry(pair[1]))) };
+}
 var MAX_CODES = 5;
 var CODE_TTL_MS = 10 * 60 * 1000;
 function generateGeneration() {
@@ -564,10 +637,11 @@ function generateGeneration() {
 }
 var CODE_ALPHABET = "ABCDEFGHJKMNPQRSTVWXYZ23456789";
 var CODE_LENGTH = 27;
-function generateCode() {
+var defaultDraw = randomInt;
+function generateCode(draw = defaultDraw) {
   let code = "";
   for (let i = 0;i < CODE_LENGTH; i++)
-    code += CODE_ALPHABET[randomInt(CODE_ALPHABET.length)];
+    code += CODE_ALPHABET[draw(CODE_ALPHABET.length)];
   return code;
 }
 function hashCode(code) {
@@ -615,7 +689,7 @@ function unregisterUser(registry, userId) {
   delete users[userId];
   return { registry: { ...registry, users }, changed: true };
 }
-function redeemCode(registry, code, now) {
+function redeemCode(registry, code) {
   const hash = hashCode(code);
   for (const userId of Object.keys(registry.users)) {
     const entry = registry.users[userId];
@@ -640,7 +714,7 @@ function createRegistryStore(dataDir, storage) {
   async function mutate(now, op) {
     let result;
     await mutator.update(path, freshRegistry, (current) => {
-      const pruned = pruneRegistry(current, now());
+      const pruned = pruneRegistry(normalizeRegistry(current), now());
       const outcome = op(pruned);
       result = outcome.result;
       return outcome.registry;
@@ -660,20 +734,32 @@ function createRegistryStore(dataDir, storage) {
       const { registry, changed } = unregisterUser(pruned, userId);
       return { registry, result: { changed } };
     }),
-    redeem: (code, now) => mutate(now, (pruned) => {
-      const { registry, outcome } = redeemCode(pruned, code, now());
-      return { registry, result: outcome };
-    }),
+    async redeem(code, now) {
+      const current = pruneRegistry(normalizeRegistry(await storage.readJsonOrFresh(path, freshRegistry, "mcp-registry")), now());
+      if (!redeemCode(current, code).outcome.ok)
+        return { ok: false };
+      return mutate(now, (pruned) => {
+        const { registry, outcome } = redeemCode(pruned, code);
+        return { registry, result: outcome };
+      });
+    },
     async generationOf(userId) {
-      const current = await storage.readJsonOrFresh(path, freshRegistry, "mcp-registry");
+      const current = normalizeRegistry(await storage.readJsonOrFresh(path, freshRegistry, "mcp-registry"));
       return generationOf(current, userId);
     },
     async listRecipients() {
-      const current = await storage.readJsonOrFresh(path, freshRegistry, "mcp-registry");
+      const current = normalizeRegistry(await storage.readJsonOrFresh(path, freshRegistry, "mcp-registry"));
       return Object.keys(current.users).map((userId) => {
         const entry = current.users[userId];
         return { userId, displayName: entry.displayName, registeredAt: entry.registeredAt };
       });
+    },
+    async recipientOf(userId) {
+      const current = normalizeRegistry(await storage.readJsonOrFresh(path, freshRegistry, "mcp-registry"));
+      const entry = entryOf(current, userId);
+      if (entry === undefined)
+        return;
+      return { userId, displayName: entry.displayName, registeredAt: entry.registeredAt };
     }
   };
 }
@@ -779,13 +865,15 @@ function createPlugin(host) {
   const limiter = createRateLimiter();
   const drainLock = createDrainLock();
   const editQueue = createEditQueue();
+  const unpersisted = createUnpersistedOutcomes();
   let disposed = false;
   const httpDeps = {
     host,
     store,
     registry,
     editQueue,
-    token: host.env.MCP_BRIDGE_TOKEN,
+    unpersisted,
+    token: host.env.MCP_BRIDGE_TOKEN?.trim() || undefined,
     limiter,
     drainLock,
     now: () => new Date,
@@ -800,9 +888,29 @@ function createPlugin(host) {
       {
         name: "redrive",
         async run(signal) {
+          for (const [requestId] of unpersisted.entries()) {
+            if (disposed || signal?.aborted === true)
+              return;
+            if (!drainLock.tryStart(requestId))
+              continue;
+            try {
+              const held = unpersisted.get(requestId);
+              if (held === undefined)
+                continue;
+              await store.set(requestId, held);
+              unpersisted.delete(requestId);
+            } catch (err) {
+              host.log.error(`persisting the outcome of delivery ${requestId} failed again`, err);
+            } finally {
+              drainLock.finish(requestId);
+            }
+          }
+          unpersisted.prune(() => new Date);
           for (const requestId of await store.list()) {
             if (disposed || signal?.aborted === true)
               return;
+            if (unpersisted.get(requestId) !== undefined)
+              continue;
             try {
               const current = await store.get(requestId);
               if (current === undefined || current.state !== "unknown")
@@ -810,6 +918,8 @@ function createPlugin(host) {
               if (!drainLock.tryStart(requestId))
                 continue;
               try {
+                if (unpersisted.get(requestId) !== undefined)
+                  continue;
                 await drainAndPersist(httpDeps, requestId, current);
               } finally {
                 drainLock.finish(requestId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rackbops/plugin-mcp",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Bridge plugin for the Discord delivery MCP (Rackbops/discord-mcp): the service side of docs/bridge-protocol.md, plus /agent registration and pairing",
   "type": "module",
   "main": "dist/plugin.js",
@@ -23,7 +23,7 @@
         "format": "^[!-~]{43,}$",
         "required": false,
         "secret": true,
-        "description": "Shared secret the Discord MCP service presents (>= 256 bits, base64url). Unset = the bridge answers 503."
+        "description": "Shared secret the Discord MCP service presents (at least 43 printable ASCII characters; 256 bits of base64url recommended). Unset = the bridge answers 503."
       }
     ],
     "destinations": [