glassframe-protocol 2.0.0 → 2.1.0

package/dist/src/ui/ControlPanel.js

@@ -74,24 +74,51 @@ function buildMetricsMessage(frame, guildId, scope = "guild") {
         .map(([name, ms]) => `${name}: ${ms}ms avg`)
         .join("\n") || "no samples yet";
 
+    const queueNote = (q) =>
+      q.pending > 0
+        ? `-# ${q.pending} task(s) queued behind the concurrency cap - normal during a burst, worth raising the cap in config if it's constant.`
+        : "-# Nothing queued - everything is running as soon as it's requested.";
+
     fields.push(
       { name: "Uptime", value: `${Math.round(m.performance.uptimeMs / 60000)} min` },
-      { name: "Action queue", value: fmtQueue(m.queues.actions) },
-      { name: "AI queue", value: fmtQueue(m.queues.ai) },
-      { name: "Threat score cache (all servers)", value: fmtCache(m.caches.threatScores) },
-      { name: "Open case cache (all servers)", value: fmtCache(m.caches.openCases) },
-      { name: "Groq verdict cache (all servers)", value: fmtCache(m.caches.groqVerdicts) },
-      { name: "Average latency", value: fmtLatency }
+      { name: "Action queue", value: `${fmtQueue(m.queues.actions)}\n${queueNote(m.queues.actions)}` },
+      { name: "AI queue", value: `${fmtQueue(m.queues.ai)}\n${queueNote(m.queues.ai)}` },
+      {
+        name: "Threat score cache (all servers)",
+        value: `${fmtCache(m.caches.threatScores)}\n-# One entry per member with any recent signal, across every server - this decays and self-prunes, so a high size alone isn't a problem.`
+      },
+      {
+        name: "Open case cache (all servers)",
+        value: `${fmtCache(m.caches.openCases)}\n-# Members currently inside their debounce window after being actioned - this is what stops a repeat trip from re-punishing or re-logging.`
+      },
+      {
+        name: "Groq verdict cache (all servers)",
+        value: `${fmtCache(m.caches.groqVerdicts)}\n-# A high hit rate means repeated/near-identical messages are being caught without a fresh API call each time.`
+      },
+      { name: "Average latency", value: fmtLatency || "no samples yet" }
     );
   } else {
     const gm = frame.getGuildMetrics(guildId);
     const statusLines = REAL_LAYERS.map((l) => `${gm.status[l] ? "ACTIVE" : "inactive"} - ${l}`).join("\n");
+    const activeCount = REAL_LAYERS.filter((l) => gm.status[l]).length;
 
     fields.push(
-      { name: "Layers", value: statusLines },
-      { name: "Flagged members right now", value: String(gm.flaggedMembers) },
-      { name: "Open cases", value: String(gm.openCases) },
-      { name: "Whitelisted users", value: String(gm.whitelistSize) }
+      {
+        name: "Layers",
+        value: `${statusLines}\n-# ${activeCount === 0 ? "Nothing is armed yet - use the panel or autoStart to turn a layer on." : `${activeCount}/4 layers watching this server.`}`
+      },
+      {
+        name: "Flagged members right now",
+        value: `${gm.flaggedMembers}\n-# Members with a live risk score above zero. This naturally decays over time on its own - a number that keeps climbing is worth a closer look, one that holds steady usually isn't.`
+      },
+      {
+        name: "Open cases",
+        value: `${gm.openCases}\n-# Members currently in their post-action cooldown window. A repeat trip within it escalates the same case rather than opening (or logging) a new one.`
+      },
+      {
+        name: "Whitelisted users",
+        value: `${gm.whitelistSize}\n-# Users exempt from punitive action in this server specifically - whitelisting elsewhere doesn't affect this count.`
+      }
     );
   }
 
@@ -119,4 +146,107 @@ function buildMetricsMessage(frame, guildId, scope = "guild") {
   return { flags: MessageFlags.IsComponentsV2, components: [container] };
 }
 
-module.exports = { buildPanel, buildMetricsMessage, BUTTONS };
+const ENGINE_PAGES = [
+  { id: "overview", label: "Overview" },
+  { id: "servers", label: "Servers" },
+  { id: "ai", label: "AI" },
+  { id: "performance", label: "Performance" },
+  { id: "logs", label: "Activity Log" }
+];
+
+/**
+ * The owner-only `!gf engine` dashboard - everything running across every
+ * guild at once, split into 5 pages so each one has room to actually go
+ * deep instead of cramming everything into one message. Built from
+ * `frame.getEngineReport()`. Reaching the FIRST page requires
+ * verifyEnginePassword() (see GlassFrame.js) if one is configured;
+ * navigating between pages afterward only re-checks isOwner() on the
+ * clicking Discord identity, not the password again.
+ */
+function buildEnginePage(report, page = "overview") {
+  const container = new ContainerBuilder().setAccentColor(0x5865f2);
+  container.addTextDisplayComponents(
+    new TextDisplayBuilder().setContent(
+      `**GlassFrame Protocol - Engine**\n${report.version.name} v${report.version.version} | up ${Math.round(report.uptimeMs / 60000)} min | serving ${report.guildCount} server(s)`
+    )
+  );
+  container.addSeparatorComponents(new SeparatorBuilder().setSpacing(SeparatorSpacingSize.Small));
+
+  if (page === "overview") {
+    const layerLines = Object.entries(report.layerAdoption)
+      .map(([name, count]) => `${name}: armed in ${count}/${report.guildCount} server(s)`)
+      .join("\n");
+    container.addTextDisplayComponents(
+      new TextDisplayBuilder().setContent(`**Layer adoption across every server**\n${layerLines}`)
+    );
+  } else if (page === "servers") {
+    const lines = report.busiestGuilds.length
+      ? report.busiestGuilds.map((g, i) => `${i + 1}. ${g.name} (${g.guildId}) - ${g.count} events recorded`).join("\n")
+      : "No activity recorded yet.";
+    container.addTextDisplayComponents(
+      new TextDisplayBuilder().setContent(`**Busiest servers, ranked by event volume**\n${lines}`)
+    );
+    container.addSeparatorComponents(new SeparatorBuilder().setSpacing(SeparatorSpacingSize.Small));
+    container.addTextDisplayComponents(
+      new TextDisplayBuilder().setContent(
+        "-# \"Events\" counts messages/joins/audit entries any layer processed for that server since this process started - it resets on restart, and isn't a measure of how much trouble a server is causing, just how much traffic it has."
+      )
+    );
+  } else if (page === "ai") {
+    const lines = [
+      `Groq available: ${report.ai.available ? "yes" : "no (no keys configured)"}`,
+      `Key pool: ${report.ai.keyCount} total, ${report.ai.keysOnCooldown} currently on cooldown`,
+      `Calls in the last minute: ${report.ai.callsLastMinute}`,
+      `Total classify() calls this run: ${report.ai.totalCallsRecorded}`,
+      `Verdict cache: ${report.metrics.caches.groqVerdicts.size} entries, ${report.metrics.caches.groqVerdicts.hits} hits / ${report.metrics.caches.groqVerdicts.misses} misses`
+    ].join("\n");
+    container.addTextDisplayComponents(new TextDisplayBuilder().setContent(`**AI moderation usage**\n${lines}`));
+  } else if (page === "performance") {
+    const m = report.metrics;
+    const fmtCache = (c) => `size ${c.size} | hits ${c.hits} | misses ${c.misses} | evictions ${c.evictions}`;
+    const fmtQueue = (q) => `active ${q.active}/${q.concurrency} | pending ${q.pending} | completed ${q.completed} | failed ${q.failed}`;
+    const latencyLines =
+      Object.entries(m.performance.avgLatencyMs)
+        .map(([name, ms]) => `${name}: ${ms}ms avg`)
+        .join("\n") || "no samples yet";
+
+    container.addTextDisplayComponents(
+      new TextDisplayBuilder().setContent(
+        `**Queues**\nAction queue: ${fmtQueue(m.queues.actions)}\nAI queue: ${fmtQueue(m.queues.ai)}`
+      )
+    );
+    container.addSeparatorComponents(new SeparatorBuilder().setSpacing(SeparatorSpacingSize.Small));
+    container.addTextDisplayComponents(
+      new TextDisplayBuilder().setContent(
+        `**Caches**\nThreat scores: ${fmtCache(m.caches.threatScores)}\nOpen cases: ${fmtCache(m.caches.openCases)}\nGroq verdicts: ${fmtCache(m.caches.groqVerdicts)}`
+      )
+    );
+    container.addSeparatorComponents(new SeparatorBuilder().setSpacing(SeparatorSpacingSize.Small));
+    container.addTextDisplayComponents(new TextDisplayBuilder().setContent(`**Average latency**\n${latencyLines}`));
+  } else if (page === "logs") {
+    const lines = report.recentLogs.length
+      ? report.recentLogs
+          .map((e) => `[${new Date(e.at).toISOString().slice(11, 19)}] ${e.guildName} - ${e.title}${e.layer ? ` (${e.layer})` : ""}`)
+          .join("\n")
+      : "Nothing logged yet.";
+    container.addTextDisplayComponents(
+      new TextDisplayBuilder().setContent(`**Recent activity, every server (last ${report.recentLogs.length})**\n${lines}`)
+    );
+  }
+
+  container.addSeparatorComponents(new SeparatorBuilder().setSpacing(SeparatorSpacingSize.Small));
+  const row = new ActionRowBuilder().addComponents(
+    ENGINE_PAGES.map((p) =>
+      new ButtonBuilder()
+        .setCustomId(`gfp_engine_${p.id}`)
+        .setLabel(p.label)
+        .setStyle(p.id === page ? ButtonStyle.Success : ButtonStyle.Secondary)
+    )
+  );
+  container.addActionRowComponents(row);
+  container.addTextDisplayComponents(new TextDisplayBuilder().setContent("-# GlassFrame Protocol - owner-only view"));
+
+  return { flags: MessageFlags.IsComponentsV2, components: [container] };
+}
+
+module.exports = { buildPanel, buildMetricsMessage, buildEnginePage, ENGINE_PAGES, BUTTONS };

package/dist/src/utils/nlpEngine.js

@@ -103,9 +103,9 @@ const PHISHING_LEXICON = {
 };
 
 const RAID_CALLOUT_LEXICON = {
-  strong: new Set(["raid", "nuke", "spam", "flood", "wipe", "destroy", "invite", "bot"]),
+  strong: new Set(["raid", "raiding", "raids", "raided", "nuke", "nuking", "spam", "spamming", "flood", "wipe", "destroy", "invite", "bot"]),
   weak: new Set(["server", "join", "everyone", "ping", "mass"]),
-  bigrams: new Set(["raid this", "nuke server", "mass ping", "spam bots", "join now"])
+  bigrams: new Set(["raid this", "nuke server", "mass ping", "spam bots", "join now", "start raiding"])
 };
 
 function suspiciousUsernameEntropy(username, floor, ceiling) {

package/docs/CACHE_ARCHITECTURE.md

@@ -37,6 +37,11 @@ windows with no need for hit/miss stats: `AntiRaidLayer.joinTimestamps` /
 are swept lazily - old timestamps are filtered out on the next write rather
 than on a timer, since they're only ever read right after a write.
 
+`SmartLogger.recentLogs` is a fixed-size array (last 30, newest first, not
+a `ProtocolCache`) recording every log event across every guild - it's what
+powers the owner-only `!gf engine` dashboard's Activity Log page. See
+`docs/ENGINE.md`.
+
 Bounded-concurrency queues (`frame.actionQueue`, `frame.aiQueue`) and the
 internal metrics collector (`frame.performance`) are a separate concern from
 caching - see `docs/PERFORMANCE.md`.

package/docs/COMMANDS.md

@@ -18,7 +18,19 @@ running twice or getting a "slow down" reply of its own.
 | `!gf phishing list` | Lists every blocked domain. |
 | `!gf whitelist add <userId>` | Exempts a user from punitive action **in this server**. |
 | `!gf whitelist remove <userId>` | Removes that exemption for this server. |
-| `!gf help` | Lists these commands. |
+| `!gf prefix set <newPrefix>` | Changes this server's own command prefix. |
+| `!gf prefix reset` | Goes back to the default prefix. |
+| `!gf help` | Lists these commands (this list, minus `engine` - see below). |
+
+There is also an owner-only `!gf engine` command - deliberately left out of
+`!gf help` and out of this table's normal flow on purpose. See
+`docs/ENGINE.md`.
+
+Each server can set its own prefix (`!gf prefix set`) - the default from
+`config.prefix` always still works too, as a fallback, in case a server
+forgets its custom one. If a custom prefix happens to overlap with the
+default (e.g. custom `!` vs. default `!gf `), the longer one is tried
+first.
 
 Everything above operates on the server the command was sent in - arming
 AntiRaid, whitelisting someone, or checking status in one server has no

package/docs/ENGINE.md

@@ -0,0 +1,83 @@
+# The Engine Dashboard
+
+`!gf engine` is a bot-wide, cross-server dashboard for whoever actually runs
+the bot - not a per-server admin tool. It shows things a single server's
+admin shouldn't be able to see about *other* servers (which server is
+busiest, bot-wide AI usage, a live feed of what's happening everywhere), so
+it has its own, separate permission model from every other command.
+
+It is deliberately **not** listed in `!gf help` or `docs/COMMANDS.md`'s
+in-Discord command table - a random server admin shouldn't even know it
+exists. You're expected to learn about it from this file.
+
+## Who can use it
+
+Two independent checks, not one:
+
+1. **`isOwner(userId)`** - you must be listed in `options.owners` when you
+   construct `GlassFrame`. This is required, full stop, for the command
+   itself *and* every page-navigation button click afterward.
+2. **A password** (optional) - if `config.engine.password` is set, the
+   initial `!gf engine <password>` command also needs the correct password.
+   Page-navigation button clicks after that don't re-prompt for it, since a
+   button click is already tied to a real, verified Discord identity - only
+   the text-command entry point needs the second factor.
+
+```js
+const frame = new GlassFrame(client, {
+  getLogChannel: /* ... */,
+  owners: ["your-discord-user-id"],
+  config: {
+    engine: {
+      password: process.env.GLASSFRAME_ENGINE_PASSWORD // never hardcode a real one
+    }
+  }
+});
+```
+
+Leave `config.engine.password` unset to skip the second factor and rely on
+the owners list alone.
+
+## What happens to the password
+
+Typing a password into a normal Discord message means it briefly sits in
+plain text in a channel, visible to anyone watching and to Discord's own
+message history. GlassFrame does two things about that:
+
+- The command message is **deleted immediately** after being checked,
+  whether the password was right or wrong.
+- Wrong guesses count toward a **lockout** -
+  `config.engine.maxAttempts` wrong attempts (default 3) locks that user
+  out for `config.engine.lockoutMs` (default 10 minutes), making
+  brute-forcing impractical.
+
+Use a private channel (or a channel only you can see) for this command
+regardless - deletion happens right after Discord delivers the message, not
+before anyone in the channel could have glimpsed it.
+
+## The five pages
+
+One row of tab buttons switches between them; the active tab is highlighted.
+
+| Page | Shows |
+|---|---|
+| **Overview** | Version, uptime, guild count, layer adoption across every server |
+| **Servers** | The busiest servers ranked by event volume since this process started |
+| **AI** | Groq key pool status, cooldowns, call volume, verdict cache hit rate |
+| **Performance** | Action/AI queue depth, all three cache stats, average latency per operation |
+| **Activity Log** | The last several things logged anywhere, any server, newest first |
+
+All of it comes from one call: `frame.getEngineReport()`, if you want the
+raw data instead of the rendered message (for your own dashboard, an API
+endpoint, whatever).
+
+## "Busiest" and the activity log, precisely
+
+- **Busiest** is a count of events (messages/joins/audit entries) any armed
+  layer processed for that server, tracked in memory since the process
+  started - it resets on restart and isn't a judgment about which server is
+  causing trouble, just which one has the most traffic.
+- The **activity log** is the last 30 events logged anywhere (any server,
+  any layer), kept in memory by `SmartLogger` - see
+  `docs/CACHE_ARCHITECTURE.md`. The dashboard shows the most recent 10 of
+  those.

package/docs/PROTOCOL_LAYERS.md

@@ -83,13 +83,52 @@ that server*, and again on demand via `!gf scan`. It reports flags, never
 actions - a human decides what, if anything, to do about a role that looks
 like impersonation bait or quietly holds dangerous permissions.
 
-## Adding a fifth layer
-
-Extend `Layer`, implement `attach()` (register your event listener(s) once;
-gate all real work behind `this.isEnabled(guildId)`), report signals via
-`this.frame.punishmentEngine.report({ guild, member, layer, weight, reason })`,
-register the instance in `GlassFrame`'s `this.layers` map, and add a button
-in `src/ui/ControlPanel.js` if you want it on the panel. Nothing else in the
-pipeline needs to know the new layer exists - per-guild enable/disable,
-state persistence, and metrics all come from the base `Layer` class for
-free.
+## Adding a layer without editing the library
+
+`frame.registerLayer(name, layerInstance)` is the supported way to do this
+now - no need to edit `GlassFrame.js`'s `this.layers` map by hand.
+`layerInstance` must extend `core/Layer`: implement `attach()` (register
+your event listener(s) once - it's called exactly once, at registration),
+gate all real work behind `this.isEnabled(guildId)`, and report signals via
+`this.frame.punishmentEngine.report({ guild, member, layer, weight, reason })`.
+Per-guild enable/disable, state persistence, and `!gf status`/`!gf metrics`
+all pick it up automatically, since they iterate `frame.layers` rather than
+a fixed list. It does **not** get a button on the 5-button panel
+automatically (that stays fixed at exactly 5) - toggle it with
+`frame.enableLayer(name, guildId)` in code, or build your own command.
+
+```js
+const Layer = require("glassframe-protocol/src/core/Layer");
+
+class LinkAgeLayer extends Layer {
+  constructor(frame) { super("linkAge", frame); }
+  attach() {
+    this._listen(this.client, "messageCreate", (message) => this._handle(message).catch(() => {}));
+  }
+  async _handle(message) {
+    if (!message.guild || message.author.bot) return;
+    if (!this.isEnabled(message.guild.id)) return;
+    // ... your detection logic, then:
+    // await this.frame.punishmentEngine.report({ guild: message.guild, member: message.member, layer: "linkAge", weight: 40, reason: "..." });
+  }
+}
+
+frame.registerLayer("linkAge", new LinkAgeLayer(frame));
+```
+
+## Custom punishment actions
+
+`frame.registerAction(name, handler)` adds an action beyond the built-in
+ban/kick/timeout/quarantine, so `config.punishment.ladder` can reference it
+by name. `handler` is `async (member, record) => {}` and runs through the
+same bounded-concurrency action queue as the built-in ones.
+
+```js
+frame.registerAction("addMutedRole", async (member) => {
+  const role = member.guild.roles.cache.find((r) => r.name === "Muted");
+  if (role) await member.roles.add(role);
+});
+```
+```js
+config: { punishment: { ladder: { medium: "addMutedRole" } } }
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glassframe-protocol",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "A layered, self-contained Discord security engine - AntiRaid, AntiNuke, Basic Security, and optional Groq-powered AI Moderation sharing one threat-scoring and punishment pipeline. Prefix commands only, Components V2 output, no slash commands.",
   "main": "dist/index.js",
   "files": [