@inetafrica/open-claudia 3.0.15 → 3.0.17

package/channels/spaces/state.js

@@ -0,0 +1,178 @@
+// Persistent per-task cursor + processed-notification set for the Spaces
+// conversational plane.
+//
+// The adapter's in-memory _seen set only dedups within a single process life.
+// This store survives restarts so a notification a previous process already
+// worked (redelivered on a socket reconnect or a REST catch-up after a bounce)
+// is not re-handled. It also keeps a per-task cursor — where the bot last
+// engaged on each task — for the advisory task loop and on-demand status.
+//
+// Parent-process only. Small, capped, atomic writes.
+
+const path = require("path");
+const { CONFIG_DIR } = require("../../core/config");
+const { atomicWriteFileSync, readJsonWithFallback } = require("../../core/fsutil");
+
+const STATE_FILE = path.join(CONFIG_DIR, "spaces-state.json");
+const PROCESSED_CAP = 500;
+
+let store = null;
+
+function load() {
+  if (store) return store;
+  const raw = readJsonWithFallback(STATE_FILE, null) || {};
+  const rawConn = raw.connection && typeof raw.connection === "object" ? raw.connection : {};
+  const rawCtrl = raw.control && typeof raw.control === "object" ? raw.control : {};
+  store = {
+    processed: Array.isArray(raw.processed) ? raw.processed.slice(-PROCESSED_CAP) : [],
+    tasks: raw.tasks && typeof raw.tasks === "object" ? raw.tasks : {},
+    // Connection signal (hybrid): central authoritatively lists Spaces among the
+    // bot's connected apps, OR the socket has actually received a Spaces
+    // notification (which only happens for a task the bot is a member of). Either
+    // one means "connected" — no env flag required.
+    connection: {
+      central: !!rawConn.central,
+      centralAt: rawConn.centralAt || 0,
+      socketFirstAt: rawConn.socketFirstAt || 0,
+      socketLastAt: rawConn.socketLastAt || 0,
+    },
+    // Owner control, set from chat (/spaces …) — never from env/filesystem, which
+    // the owner can't reach on a pod. `muted` is the off-switch for auto-replies;
+    // `taskLoopMode` overrides the env default posture.
+    control: {
+      muted: !!rawCtrl.muted,
+      taskLoopMode: rawCtrl.taskLoopMode || null,
+    },
+  };
+  return store;
+}
+
+function save() {
+  if (!store) return;
+  try { atomicWriteFileSync(STATE_FILE, JSON.stringify(store, null, 2), { backup: true }); }
+  catch (e) { console.error("spaces-state: write failed:", e.message); }
+}
+
+// Record a notification id as handled. Returns true if it was NEW (proceed),
+// false if it had already been processed in this or a previous life (skip).
+function markProcessed(notificationId) {
+  const id = String(notificationId || "");
+  if (!id) return false;
+  const s = load();
+  if (s.processed.includes(id)) return false;
+  s.processed.push(id);
+  if (s.processed.length > PROCESSED_CAP) s.processed = s.processed.slice(-PROCESSED_CAP);
+  save();
+  return true;
+}
+
+// Advance a task's cursor. Called for every task notification (awareness too)
+// so the cursor always reflects the last activity we observed on the task.
+function recordCursor(taskId, { notificationId = "", type = "" } = {}) {
+  const id = String(taskId || "");
+  if (!id) return;
+  const s = load();
+  const cur = s.tasks[id] || { count: 0 };
+  s.tasks[id] = {
+    lastNotificationId: String(notificationId || cur.lastNotificationId || ""),
+    lastType: String(type || cur.lastType || ""),
+    lastAt: new Date().toISOString(),
+    count: (cur.count || 0) + 1,
+  };
+  save();
+}
+
+function getCursor(taskId) {
+  const s = load();
+  return s.tasks[String(taskId || "")] || null;
+}
+
+function snapshot() {
+  const s = load();
+  return { tasks: s.tasks, processedCount: s.processed.length };
+}
+
+// --- Connection signal -----------------------------------------------------
+
+// Called on every inbound Spaces notification. Receiving one is proof the bot is
+// a member of that task's space, so it flips the socket-connected signal on.
+function markSocketConnected() {
+  const s = load();
+  const now = Date.now();
+  if (!s.connection.socketFirstAt) s.connection.socketFirstAt = now;
+  s.connection.socketLastAt = now;
+  save();
+}
+
+// Called by the connected-apps poller with central's authoritative answer to
+// "is Spaces among my connected apps?". Persisted so a restart keeps the signal
+// until the next poll refreshes it.
+function setCentralConnected(connected) {
+  const s = load();
+  const val = !!connected;
+  if (s.connection.central === val && s.connection.centralAt) return;
+  s.connection.central = val;
+  s.connection.centralAt = Date.now();
+  save();
+}
+
+// Hybrid: connected if central says so, or the socket has ever delivered a
+// Spaces notification. Membership is the real-world gate — you can't receive a
+// notification for a space you're not in — so socket-ever-connected is a safe,
+// sticky signal.
+function isConnected() {
+  const s = load();
+  return !!(s.connection.central || s.connection.socketFirstAt);
+}
+
+// --- Owner control (from chat) ---------------------------------------------
+
+function setMuted(muted) {
+  const s = load();
+  s.control.muted = !!muted;
+  save();
+  return s.control.muted;
+}
+
+function setTaskLoopMode(mode) {
+  const s = load();
+  const m = String(mode || "").toLowerCase();
+  s.control.taskLoopMode = ["advisory", "autonomous", "off"].includes(m) ? m : null;
+  save();
+  return s.control.taskLoopMode;
+}
+
+// The task-working posture for engaged Spaces turns: chat override wins, else the
+// env default the caller passes ("advisory" unless overridden).
+function taskLoopMode(envDefault = "advisory") {
+  const s = load();
+  return s.control.taskLoopMode || String(envDefault || "advisory").toLowerCase();
+}
+
+// The single gate the adapter/loopback/access all read: auto-replies are live
+// when the bot is connected to Spaces AND the owner hasn't paused them.
+function conversationalActive() {
+  const s = load();
+  return isConnected() && !s.control.muted;
+}
+
+// For /spaces status.
+function controlSnapshot() {
+  const s = load();
+  return {
+    connected: isConnected(),
+    central: s.connection.central,
+    socketFirstAt: s.connection.socketFirstAt,
+    socketLastAt: s.connection.socketLastAt,
+    muted: s.control.muted,
+    conversationalActive: conversationalActive(),
+    taskLoopMode: taskLoopMode(),
+    taskLoopOverride: s.control.taskLoopMode,
+  };
+}
+
+module.exports = {
+  markProcessed, recordCursor, getCursor, snapshot, STATE_FILE,
+  markSocketConnected, setCentralConnected, isConnected,
+  setMuted, setTaskLoopMode, taskLoopMode, conversationalActive, controlSnapshot,
+};

package/core/access.js

@@ -52,6 +52,16 @@ function isChatAuthorized(chatId) {
   if (matchesTransportOwner()) return true;
   const id = String(chatId || "");
   if (!id) return false;
+  // Spaces task threads authorize by participation: the bot only receives a
+  // Spaces notification for a task it follows/was mentioned on, so the inbound
+  // itself is the authorization signal. Effective only while the conversational
+  // plane is active (connected to Spaces AND the owner hasn't paused replies).
+  try {
+    if (currentTransport() === "spaces"
+      && require("../channels/spaces/state").conversationalActive()) {
+      return true;
+    }
+  } catch (e) {}
   if (CHAT_IDS.includes(id)) return true;
   try {
     const auth = JSON.parse(fs.readFileSync(AUTH_FILE, "utf-8"));

package/core/actions.js

@@ -443,6 +443,14 @@ async function handleAction(envelope) {
         : `Could not deliver the reply.`);
     }
 
+    // Mirror the owner's decision back into the originating Spaces task thread
+    // (non-binding status; the binding decision happened here). Scoped to plain
+    // tool runs — external reply/action escalations resume their own turn and
+    // report there, so mirroring here would double-post.
+    if (rec.kind === "tool" && rec.adapter === "spaces") {
+      try { require("../channels/spaces/approval-mirror").mirrorOutcome(rec).catch(() => {}); } catch (e) {}
+    }
+
     // If a second press disagreed, rec.status still holds the FIRST decision.
     const label = `${rec.tool}${rec.verb ? " " + rec.verb : ""}`;
     // Always-allow on an external ACTION escalation folds the command into the

package/core/adapter-registry.js

@@ -12,6 +12,7 @@ const { setAdapters } = require("./scheduler");
 
 const { TelegramAdapter } = require("../channels/telegram/adapter");
 const { KazeeAdapter } = require("../channels/kazee/adapter");
+const { SpacesAdapter } = require("../channels/spaces/adapter");
 const { VoiceAdapter } = require("../channels/voice/adapter");
 const { WebAdapter } = require("../channels/web/adapter");
 
@@ -22,6 +23,7 @@ let actionHandler = null;
 function createAdapter(spec) {
   if (spec.type === "telegram") return new TelegramAdapter({ id: spec.id, ...spec.opts });
   if (spec.type === "kazee") return new KazeeAdapter({ id: spec.id, ...spec.opts });
+  if (spec.type === "spaces") return new SpacesAdapter({ id: spec.id, ...spec.opts });
   if (spec.type === "voice") return new VoiceAdapter({ id: spec.id, ...spec.opts });
   if (spec.type === "web") return new WebAdapter({ id: spec.id, ...spec.opts });
   console.error(`Unknown adapter type: ${spec.type}`);

package/core/config.js

@@ -193,6 +193,10 @@ const FULL_PATH = [
 // for the bot token (the actual secret). Override with KAZEE_URL if ever needed.
 const KAZEE_DEFAULT_URL = "https://chat.inet.africa";
 
+// Kazee Spaces is fixed infrastructure too. The bot authenticates with its own
+// kzb_ token (KAZEE_BOT_TOKEN) — Spaces accepts it directly, so no new secret.
+const SPACES_DEFAULT_URL = "https://api.spaces.kazee.africa";
+
 // Channels: declarative list of {id, type, opts}. Defaults to telegram for
 // backwards compat with installs predating CHANNELS.
 function loadChannels() {
@@ -231,6 +235,32 @@ function loadChannels() {
         type: "kazee",
         opts: { url, token, ownerUserId, botUserId },
       });
+    } else if (type === "spaces") {
+      // Conversational plane for Kazee Spaces. Bot authenticates with its own
+      // kzb_ token (the same KAZEE_BOT_TOKEN the connected-apps poller uses).
+      const url = config.SPACES_URL || SPACES_DEFAULT_URL;
+      const token = config.KAZEE_BOT_TOKEN;
+      if (!token) {
+        console.error(`CHANNELS includes ${entry} but KAZEE_BOT_TOKEN is unset — skipping.`);
+        continue;
+      }
+      channels.push({
+        id,
+        type: "spaces",
+        opts: {
+          url,
+          token,
+          ownerUserId: config.SPACES_OWNER_USER_ID || "",
+          // Conversational auto-replies are no longer env-gated: the adapter
+          // enables them itself once Spaces is CONNECTED (central lists it, or
+          // the socket receives a notification) and the owner hasn't paused via
+          // /spaces. The socket always starts here for awareness.
+          // taskLoopMode is only the DEFAULT posture; /spaces mode overrides it
+          // live. "advisory" = read/reason/recommend; "autonomous" = work to
+          // completion (writes still hit the owner-approval gate); "off".
+          taskLoopMode: String(config.OC_SPACES_TASK_LOOP || process.env.OC_SPACES_TASK_LOOP || "advisory").toLowerCase(),
+        },
+      });
     } else if (type === "voice") {
       const token = config.VOICE_BRIDGE_TOKEN;
       if (!token) {
@@ -251,6 +281,23 @@ function loadChannels() {
       console.error(`Unknown channel type: ${type} — skipping.`);
     }
   }
+  // Auto-include the Spaces channel whenever the bot has its own kzb_ token, even
+  // if CHANNELS didn't list it. Spaces is fixed infra on the same token as Kazee
+  // chat, and the owner can't edit CHANNELS on a pod — so "have token ⇒ Spaces
+  // available" is what makes auto-enable reachable without touching env. It's
+  // self-gating: no Spaces membership ⇒ no notifications ⇒ no replies.
+  if ((config.KAZEE_BOT_TOKEN) && !channels.some((c) => c.type === "spaces")) {
+    channels.push({
+      id: "spaces",
+      type: "spaces",
+      opts: {
+        url: config.SPACES_URL || SPACES_DEFAULT_URL,
+        token: config.KAZEE_BOT_TOKEN,
+        ownerUserId: config.SPACES_OWNER_USER_ID || "",
+        taskLoopMode: String(config.OC_SPACES_TASK_LOOP || process.env.OC_SPACES_TASK_LOOP || "advisory").toLowerCase(),
+      },
+    });
+  }
   return channels;
 }
 
@@ -305,6 +352,7 @@ module.exports = {
   UTILITY_PURPOSE_PROVIDERS,
   ensureRuntimeDirectories,
   KAZEE_DEFAULT_URL,
+  SPACES_DEFAULT_URL,
   BOT_DIR,
   CONFIG_DIR,
   TOKEN, CHAT_IDS, CHAT_ID,

package/core/connected-apps.js

@@ -0,0 +1,235 @@
+// Connected-apps subsystem — the data/awareness plane.
+//
+// The bot uses its OWN control-plane token (KAZEE_BOT_TOKEN, an opaque kzb_…)
+// to ask inet-central "which apps am I connected to?" (GET
+// /api/principal/applications — the self-service endpoint added alongside this),
+// then, for each connected app that has a registered connector, polls it for
+// awareness (Spaces first: unread notifications + tasks). This runs ONLY in the
+// parent bot process — the token is a CONTROL_PLANE_KEY stripped from every
+// provider/tool subprocess, so a connector can never leak into a coding-agent
+// child.
+//
+// Scalable by construction: adding an app = drop in a connector + list the app
+// in central. No core changes. This module knows nothing app-specific beyond
+// the connectors that register themselves.
+//
+// SAFETY: everything here is READ-ONLY. It discovers and observes; it never
+// writes to central or to any app. New items are recorded in connected-apps.json
+// for on-demand querying — no agent turn is auto-triggered from this plane. The
+// conversational plane (auto-replies) is a separate, opt-in channel adapter.
+
+const https = require("https");
+const http = require("http");
+const path = require("path");
+const { URL } = require("url");
+const { config, CONFIG_DIR } = require("./config");
+const { atomicWriteFileSync, readJsonWithFallback } = require("./fsutil");
+const { truthy } = require("../project-transcripts");
+
+const STORE_FILE = path.join(CONFIG_DIR, "connected-apps.json");
+const CENTRAL_URL = (config.CENTRAL_URL || "https://central.inet.africa").replace(/\/$/, "");
+
+const APPS_REFRESH_MS = 15 * 60 * 1000; // re-ask central which apps we're on
+const POLL_INTERVAL_MS = 90 * 1000;     // per-app awareness poll cadence
+const BACKOFF_BASE_MS = 60 * 1000;
+const BACKOFF_MAX_MS = 30 * 60 * 1000;
+const INBOX_CAP = 100;
+
+let timer = null;
+let store = null;
+const connectors = new Map(); // appKey -> connector
+
+function botToken() {
+  return config.KAZEE_BOT_TOKEN || process.env.KAZEE_BOT_TOKEN || "";
+}
+
+function loadStore() {
+  const raw = readJsonWithFallback(STORE_FILE, null) || {};
+  return {
+    appsRefreshedAt: raw.appsRefreshedAt || 0,
+    apps: Array.isArray(raw.apps) ? raw.apps : [],
+    perApp: raw.perApp && typeof raw.perApp === "object" ? raw.perApp : {},
+  };
+}
+
+function saveStore() {
+  try { atomicWriteFileSync(STORE_FILE, JSON.stringify(store, null, 2), { backup: true }); }
+  catch (e) { console.error("connected-apps: store write failed:", e.message); }
+}
+
+function appState(key) {
+  if (!store.perApp[key]) {
+    store.perApp[key] = { lastPollAt: 0, status: "idle", backoffUntil: 0, backoffMs: 0, seen: [], inbox: [] };
+  }
+  return store.perApp[key];
+}
+
+function getJson(baseUrl, urlPath, token) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(baseUrl.replace(/\/$/, "") + urlPath);
+    const lib = u.protocol === "https:" ? https : http;
+    const req = lib.request(
+      {
+        method: "GET",
+        hostname: u.hostname,
+        port: u.port || (u.protocol === "https:" ? 443 : 80),
+        path: u.pathname + (u.search || ""),
+        headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+      },
+      (res) => {
+        let chunks = "";
+        res.on("data", (c) => { chunks += c; });
+        res.on("end", () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            try { resolve(chunks ? JSON.parse(chunks) : {}); }
+            catch (e) { resolve({}); }
+          } else {
+            reject(new Error(`GET ${urlPath} → ${res.statusCode}: ${chunks.slice(0, 200)}`));
+          }
+        });
+      },
+    );
+    req.on("error", reject);
+    req.setTimeout(30000, () => req.destroy(new Error(`GET ${urlPath} timeout`)));
+    req.end();
+  });
+}
+
+// Ask central which apps this bot token is a member of. Returns [] on failure
+// (caller keeps the last-known list).
+async function fetchConnectedApps() {
+  const token = botToken();
+  if (!token) return [];
+  const res = await getJson(CENTRAL_URL, "/api/principal/applications", token);
+  return Array.isArray(res?.applications) ? res.applications : [];
+}
+
+function registerConnector(connector) {
+  if (!connector || !connector.appKey) throw new Error("connector needs an appKey");
+  connectors.set(connector.appKey, connector);
+}
+
+function connectorFor(app) {
+  for (const c of connectors.values()) {
+    try { if (c.match(app)) return c; } catch (e) {}
+  }
+  return null;
+}
+
+// Record awareness items into the app's capped inbox, deduped by id. Returns
+// the count of genuinely new items.
+function recordItems(state, items) {
+  const seen = new Set(state.seen);
+  let added = 0;
+  for (const it of items) {
+    const id = String(it.id || "");
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    state.inbox.unshift(it);
+    added += 1;
+  }
+  state.seen = [...seen].slice(-INBOX_CAP * 2);
+  state.inbox = state.inbox.slice(0, INBOX_CAP);
+  return added;
+}
+
+async function pollApp(app) {
+  const key = String(app.id || app.name);
+  const state = appState(key);
+  const now = Date.now();
+  if (state.backoffUntil && now < state.backoffUntil) return;
+  const connector = connectorFor(app);
+  if (!connector) { state.status = "no-connector"; return; }
+  try {
+    const items = await connector.poll(app, botToken());
+    const added = recordItems(state, items || []);
+    state.lastPollAt = now;
+    state.status = "ok";
+    state.backoffMs = 0;
+    state.backoffUntil = 0;
+    if (added) console.log(`connected-apps: ${connector.appKey} — ${added} new item(s)`);
+  } catch (e) {
+    state.status = `error: ${e.message}`;
+    state.backoffMs = Math.min(state.backoffMs ? state.backoffMs * 2 : BACKOFF_BASE_MS, BACKOFF_MAX_MS);
+    state.backoffUntil = now + state.backoffMs;
+    console.error(`connected-apps: ${key} poll failed, backing off ${Math.round(state.backoffMs / 1000)}s:`, e.message);
+  }
+}
+
+async function tick() {
+  const now = Date.now();
+  if (now - store.appsRefreshedAt > APPS_REFRESH_MS) {
+    try {
+      const apps = await fetchConnectedApps();
+      if (apps.length || store.apps.length === 0) {
+        store.apps = apps;
+        store.appsRefreshedAt = now;
+      }
+    } catch (e) {
+      console.error("connected-apps: apps refresh failed:", e.message);
+    }
+  }
+  // Central's authoritative half of the "connected ⇒ conversational" signal:
+  // tell the Spaces conversational plane whether central lists Spaces among this
+  // bot's apps. The socket half is set independently when a notification lands,
+  // so auto-replies work even before this endpoint is deployed.
+  try {
+    const spacesConnected = store.apps.some((a) => {
+      const c = connectorFor(a);
+      return c && c.appKey === "spaces";
+    });
+    require("../channels/spaces/state").setCentralConnected(spacesConnected);
+  } catch (e) {}
+
+  for (const app of store.apps) {
+    if (!connectorFor(app)) continue;
+    await pollApp(app);
+  }
+  saveStore();
+}
+
+// Public: current awareness snapshot (for an on-demand "what's in my inbox").
+function snapshot() {
+  if (!store) store = loadStore();
+  return {
+    apps: store.apps.map((a) => ({ id: a.id, name: a.name })),
+    perApp: Object.fromEntries(
+      Object.entries(store.perApp).map(([k, v]) => [k, {
+        status: v.status,
+        lastPollAt: v.lastPollAt,
+        unread: v.inbox.length,
+        inbox: v.inbox.slice(0, 20),
+      }]),
+    ),
+  };
+}
+
+function initConnectedApps() {
+  if (!truthy(config.OC_CONNECTED_APPS || process.env.OC_CONNECTED_APPS, false)) {
+    return { started: false, reason: "OC_CONNECTED_APPS disabled" };
+  }
+  if (!botToken()) {
+    return { started: false, reason: "KAZEE_BOT_TOKEN unset" };
+  }
+  store = loadStore();
+  // Register built-in connectors.
+  try { registerConnector(require("./connectors/spaces")); }
+  catch (e) { console.error("connected-apps: spaces connector load failed:", e.message); }
+  // First tick shortly after boot, then on the poll cadence.
+  setTimeout(() => { tick().catch((e) => console.error("connected-apps tick:", e.message)); }, 20000);
+  timer = setInterval(() => { tick().catch((e) => console.error("connected-apps tick:", e.message)); }, POLL_INTERVAL_MS);
+  return { started: true, connectors: [...connectors.keys()] };
+}
+
+function stopConnectedApps() {
+  if (timer) { clearInterval(timer); timer = null; }
+}
+
+module.exports = {
+  initConnectedApps,
+  stopConnectedApps,
+  registerConnector,
+  fetchConnectedApps,
+  snapshot,
+  STORE_FILE,
+};

package/core/connectors/spaces.js

@@ -0,0 +1,41 @@
+// Spaces awareness connector. Registered with the connected-apps poller; polls
+// the bot's own unread Spaces notifications (read-only) and returns them as
+// normalised awareness items. This is the data plane only — it observes and
+// records; it never replies. Replies are the separate conversational channel
+// adapter (channels/spaces/adapter.js).
+
+const { SpacesClient, contentText } = require("../../channels/spaces/client");
+const { config } = require("../config");
+
+const SPACES_URL = (config.SPACES_URL || "https://api.spaces.kazee.africa").replace(/\/$/, "");
+
+module.exports = {
+  appKey: "spaces",
+
+  // Central lists the app by name/domain. Match either.
+  match(app) {
+    const hay = `${app?.name || ""} ${app?.domainName || ""}`.toLowerCase();
+    return hay.includes("spaces");
+  },
+
+  async poll(_app, token) {
+    const client = new SpacesClient({ baseUrl: SPACES_URL, token });
+    const notifications = await client.listNotifications({ limit: 40, unreadOnly: true });
+    return notifications.map((n) => {
+      const inner = (n.data && n.data.payload) || {};
+      const actor = n.actorId || {};
+      const actorName = typeof actor === "object"
+        ? (`${actor.firstName || ""} ${actor.lastName || ""}`.trim() || actor.email || "")
+        : String(actor);
+      return {
+        id: String(n.id || n._id || ""),
+        type: String(n.category || n.type || "").toLowerCase(),
+        actorName,
+        taskId: String(n.sourceEntityId || inner.taskId || inner.targetId || ""),
+        taskTitle: inner.taskTitle || inner.targetTitle || n.title || "",
+        text: contentText(n.content || n.title || "").slice(0, 300),
+        createdAt: n.createdAt || null,
+      };
+    });
+  },
+};

package/core/handlers.js

@@ -793,6 +793,55 @@ register({
   },
 });
 
+register({
+  name: "spaces", description: "Control Kazee Spaces auto-replies (status/pause/resume/mode)",
+  args: "<status | pause | resume | mode advisory|autonomous|off>", ownerOnly: true,
+  handler: async (env, { tail }) => {
+    if (!ownerEnv(env)) return;
+    let spacesState;
+    try { spacesState = require("../channels/spaces/state"); }
+    catch (e) { return send("Spaces state unavailable — the Spaces channel isn't loaded."); }
+    const parts = (tail || "").trim().split(/\s+/).filter(Boolean);
+    const op = (parts[0] || "status").toLowerCase();
+
+    const fmtTime = (ms) => (ms ? new Date(ms).toISOString().replace("T", " ").slice(0, 16) + "Z" : "never");
+    const statusText = () => {
+      const s = spacesState.controlSnapshot();
+      const src = s.central ? "central" : (s.socketFirstAt ? "socket" : "—");
+      const replies = s.conversationalActive ? "ON" : (s.connected ? "paused" : "off (not connected)");
+      const modeLine = s.taskLoopOverride
+        ? `${s.taskLoopMode} (override)`
+        : `${s.taskLoopMode} (default)`;
+      return [
+        "<b>Kazee Spaces</b>",
+        `Connected: ${s.connected ? "yes" : "no"}${s.connected ? ` (via ${src})` : ""}`,
+        `Auto-replies: ${replies}`,
+        `Task mode: ${modeLine}`,
+        `Last notification: ${fmtTime(s.socketLastAt)}`,
+      ].join("\n");
+    };
+
+    if (op === "status") return send(statusText());
+    if (op === "pause") {
+      spacesState.setMuted(true);
+      return send("Spaces auto-replies <b>paused</b>. Mentions/replies still hit the radar; I just won't answer until you /spaces resume.\n\n" + statusText());
+    }
+    if (op === "resume") {
+      spacesState.setMuted(false);
+      return send("Spaces auto-replies <b>resumed</b>.\n\n" + statusText());
+    }
+    if (op === "mode") {
+      const m = (parts[1] || "").toLowerCase();
+      if (!["advisory", "autonomous", "off"].includes(m)) {
+        return send("Usage: /spaces mode <advisory|autonomous|off>\n\n• advisory — read, reason, recommend (no autonomous write chains)\n• autonomous — work to completion (writes still need your approval)\n• off — no task-mode framing");
+      }
+      spacesState.setTaskLoopMode(m);
+      return send(`Spaces task mode set to <b>${m}</b>.\n\n` + statusText());
+    }
+    return send("Usage: /spaces <status | pause | resume | mode advisory|autonomous|off>");
+  },
+});
+
 register({
   name: "cluster", description: "Control this bot's own deployment (status/logs/restart/start/stop/scale/sync)",
   args: "<status|logs|restart|start|stop|scale 0|1|sync>", ownerOnly: true,