@inetafrica/open-claudia 3.0.15 → 3.0.17

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## v3.0.17 — Spaces auto-enables on connection; control moves into chat
+
+- **The Spaces conversational plane no longer hides behind an env flag.** `OC_SPACES_CONVERSATIONAL` is gone. Auto-replies now enable themselves the moment the bot is **connected** to Spaces, on a hybrid signal: 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 flips it on — so it works today over the socket even before the central `/api/principal/applications` endpoint is deployed. It stays self-gating: no Spaces membership ⇒ no notifications ⇒ no replies.
+- **All control is in chat now — nothing to set on the pod.** New owner command `/spaces`: `status` (connection + whether replies are live + task mode), `pause` / `resume` (the off-switch for auto-replies; mentions still hit the radar, I just don't answer), and `mode advisory|autonomous|off` (task-working posture, overriding the env default live). State persists in `spaces-state.json`; the owner never needs filesystem or env access.
+- **The Spaces channel auto-includes whenever `KAZEE_BOT_TOKEN` is set**, even if `CHANNELS` doesn't list it — Spaces is fixed infra on the same token as Kazee chat, so "has token ⇒ Spaces available" is what makes auto-enable reachable without editing env.
+- **Agent-space / OpenClaw:** no new deps, no new env required, no schema change; Docker image builds identically (FROM the pre-baked `:base`). Existing pods pick this up on their next approved upgrade.
+
+## v3.0.16 — Spaces task loop + approval thread-mirror (dormant)
+
+- **Kazee Spaces connected-apps gains its two remaining pieces, both shipped OFF.** The task-working loop runs in **advisory** mode by default: when the bot engages a Spaces task thread, its turns for that task are serialized (one at a time, while different tasks proceed in parallel), a persistent cursor + cross-restart dedup lives in `spaces-state.json`, and a new `OC_SPACES_TASK_LOOP` mode (`advisory` | `autonomous` | `off`) selects the framing. The **approval thread-mirror** routes any write/destructive action from a Spaces-origin turn to the owner's Telegram Approve/Deny button (fail-closed if no reachable owner channel — the run stays blocked rather than posting a dead button into the thread) and mirrors a non-binding status comment into the task thread on request and on outcome.
+- **No behaviour change anywhere until you opt in.** All of it stays dormant behind the existing kill-switches (`OC_CONNECTED_APPS`, `OC_SPACES_CONVERSATIONAL`, plus the new `OC_SPACES_TASK_LOOP` which is advisory-but-inert while the others are off) and the bot still needs Spaces app-membership to receive anything. Telegram and Kazee flows are byte-identical.
+- **Agent-space / OpenClaw:** no new deps, no new env required, no schema change; Docker image builds identically (FROM the pre-baked `:base`). Existing pods pick this up on their next approved upgrade.
+
 ## v3.0.15 — the owner keeps their memory on Kazee
 
 - **Episodic recall no longer goes dark on Kazee / group chats.** Cross-conversation episodic memory (relevant snippets from the owner's past transcripts) is deliberately owner-only. The gate that decides "is this speaker the owner?" resolved the person by `findByHandle(adapter, channelId)` — but on Kazee the `channelId` is the *chat/room id*, while the owner's stored handle is their Kazee *user id*, so the lookup missed and fail-closed suppressed episodes. The owner's canonical brain, settings, and session were shared via identity unification, but this one recall layer silently went quiet — which read as "less context on Kazee." The gate now resolves the speaker by the envelope's **canonical user id** first (derived from the authenticated sender and unified across a person's linked channels), falling back to the channelId handle lookup when no canonical is in context. Fail-closed semantics for non-owners are preserved: a non-owner's canonical never matches an owner record. Regression pinned in `test-recall-relationship-gate.js` (owner recognised via canonical on a room-id channel; external still blocked).

package/bot.js

@@ -270,6 +270,18 @@ setInterval(checkForUpdates, 5 * 60 * 1000);
   try { require("./core/dream").initDream(adapters); }
   catch (e) { console.error("dream init failed:", e.message); }
 
+  // Connected-apps awareness plane (read-only, parent-process only, flag-gated
+  // OFF by default). Discovers which apps this bot is connected to via central
+  // and polls them (Spaces first). Never auto-triggers a turn.
+  try {
+    const ca = require("./core/connected-apps").initConnectedApps();
+    console.log(ca.started
+      ? `Connected-apps: ON (connectors: ${ca.connectors.join(", ")})`
+      : `Connected-apps: off (${ca.reason})`);
+  } catch (e) {
+    console.error("connected-apps init failed:", e.message);
+  }
+
   try {
     const lb = await loopback.start(registry);
     console.log(`Loopback send endpoint: ${lb.url}`);

package/channels/spaces/adapter.js

@@ -0,0 +1,238 @@
+// SpacesAdapter — the conversational plane for Kazee Spaces. Duck-types the
+// same ChannelAdapter contract as Telegram/Kazee so a Spaces task thread flows
+// through the normal router → agent turn, inheriting packs, tools, entity
+// memory and the approval policy for free. No core changes needed to make a
+// Spaces comment "think" — it's just another channel.
+//
+// Event source: the per-user "notification" socket event (instant), backed by a
+// REST poll() the connected-apps poller can call as a catch-up. Each Spaces
+// TASK maps to one conversation channel ("task:<taskId>") so a task keeps its
+// own session/state. The commenter (actorId) is the person; the task is the
+// thread — the same split every other adapter uses.
+//
+// Urgency policy (conservative, per the approved design): mentions, replies and
+// assignments ENGAGE (emit a turn); plain comment_added / task_updated /
+// reaction are awareness-only — they update the cursor and are queryable, but
+// do not auto-trigger a reply. This is the "untagged comments hit the radar
+// without auto-answering" rule.
+
+const { canonicalForChannel } = require("../../core/identity");
+const { SpacesClient, contentText } = require("./client");
+const { createSpacesSocket } = require("./socket");
+const spacesState = require("./state");
+
+// Notification `type`/`category` values that warrant a full agent turn.
+const ENGAGE_TYPES = new Set(["mention", "reply", "task_assigned"]);
+
+class SpacesAdapter {
+  constructor({ id = "spaces", url = "https://api.spaces.kazee.africa", token, ownerUserId = "", taskLoopMode = "advisory" }) {
+    this.id = id;
+    this.type = "spaces";
+    this.url = url.replace(/\/$/, "");
+    this.token = token;
+    this.ownerUserId = ownerUserId || "";
+    // Env default posture; the live value is chat-overridable via spacesState.
+    this.taskLoopModeDefault = taskLoopMode || "advisory";
+    this.client = new SpacesClient({ baseUrl: this.url, token });
+    this._listeners = { message: new Set(), action: new Set() };
+    this._socket = null;
+    this._seen = new Set(); // notification-id dedup across socket + poll
+    this._taskChains = new Map(); // taskId -> tail promise, for per-task serialization
+  }
+
+  on(event, fn) {
+    if (!this._listeners[event]) return () => {};
+    this._listeners[event].add(fn);
+    return () => this._listeners[event].delete(fn);
+  }
+
+  _emit(event, envelope) {
+    for (const fn of this._listeners[event] || []) {
+      try { Promise.resolve(fn(envelope)).catch((e) => console.error(`spaces ${event} handler:`, e.message)); }
+      catch (e) { console.error(`spaces ${event} handler:`, e.message); }
+    }
+  }
+
+  async start() {
+    this._socket = createSpacesSocket({
+      url: this.url,
+      token: this.token,
+      onNotification: (payload) => this._handleNotification(payload, "socket"),
+      onConnect: () => console.log(`Spaces socket connected (${this.url})`),
+      onDisconnect: (reason) => console.log(`Spaces socket disconnected: ${reason}`),
+      onError: (err) => console.error("Spaces socket error:", err.message),
+    });
+  }
+
+  async stop() {
+    try { this._socket?.disconnect?.(); } catch (e) {}
+    this._socket = null;
+  }
+
+  // REST catch-up. The connected-apps poller calls this on its cadence so a
+  // missed socket push (reconnect gap) still surfaces. Read-only.
+  async poll() {
+    try {
+      const notifications = await this.client.listNotifications({ limit: 40, unreadOnly: true });
+      // Oldest-first so a burst is delivered in order.
+      for (const n of notifications.reverse()) this._handleNotification(n, "poll");
+    } catch (e) {
+      console.error("Spaces poll error:", e.message);
+    }
+  }
+
+  _notificationId(payload) {
+    return String(payload?.id || payload?._id || "");
+  }
+
+  // Live task-loop posture: chat override (spacesState) wins over the env default.
+  _taskLoopMode() {
+    try { return spacesState.taskLoopMode(this.taskLoopModeDefault); }
+    catch (e) { return this.taskLoopModeDefault; }
+  }
+
+  // Notifications arrive in two shapes: the socket payload
+  // (broadcastNotification: flat {type,targetType,targetId,actorId,actorName})
+  // and the REST row ({category, actorId:{...}, sourceEntityId, data.payload}).
+  // Normalise both to one internal view.
+  _normalize(payload) {
+    const type = String(payload.type || payload.category || "").toLowerCase();
+    const data = payload.data || {};
+    const inner = data.payload || {};
+    const taskId = String(
+      (payload.targetType === "task" && payload.targetId)
+      || data.taskId
+      || inner.taskId
+      || payload.sourceEntityId
+      || inner.targetId
+      || payload.targetId
+      || "",
+    );
+    let actorId = payload.actorId;
+    let actorName = payload.actorName;
+    if (actorId && typeof actorId === "object") {
+      actorName = actorName || `${actorId.firstName || ""} ${actorId.lastName || ""}`.trim() || actorId.email;
+      actorId = actorId.id || actorId._id;
+    }
+    return {
+      type,
+      taskId,
+      actorId: actorId ? String(actorId) : "",
+      actorName: actorName || "",
+      spaceId: payload.spaceId || inner.spaceId || null,
+      title: payload.title || inner.taskTitle || inner.targetTitle || "",
+      content: contentText(payload.content || payload.title || ""),
+      deepLink: payload.deepLink || null,
+    };
+  }
+
+  _handleNotification(payload, source) {
+    const id = this._notificationId(payload);
+    if (!id || this._seen.has(id)) return;
+    this._seen.add(id);
+    if (this._seen.size > 500) {
+      const arr = [...this._seen];
+      this._seen.clear();
+      arr.slice(-250).forEach((k) => this._seen.add(k));
+    }
+
+    // Persistent dedup across restarts: a socket reconnect or a REST catch-up
+    // can redeliver a notification a previous process already handled.
+    try { if (!spacesState.markProcessed(id)) return; } catch (e) {}
+
+    const n = this._normalize(payload);
+    if (!n.taskId) return;
+
+    // Receiving any Spaces notification proves membership → mark connected. This
+    // is the socket half of the hybrid "connected ⇒ conversational" signal; no
+    // env flag needed to turn auto-replies on.
+    try { spacesState.markSocketConnected(); } catch (e) {}
+
+    // Advance this task's cursor (awareness events included) so it always
+    // reflects the last activity we observed on the task.
+    try { spacesState.recordCursor(n.taskId, { notificationId: id, type: n.type }); } catch (e) {}
+
+    // Awareness-only types never auto-trigger a turn. They still fire an
+    // "awareness" listener (if any) so the poller can track/surface them.
+    // conversationalActive() = connected (central or socket) AND not owner-muted.
+    let active = false;
+    try { active = spacesState.conversationalActive(); } catch (e) {}
+    const engage = active && ENGAGE_TYPES.has(n.type);
+    this._emit("awareness", { adapter: this, notificationId: id, source, ...n });
+    if (!engage) return;
+
+    const channelId = `task:${n.taskId}`;
+    const envelope = {
+      adapter: this,
+      channelId,
+      canonicalUserId: canonicalForChannel("spaces", n.actorId || n.taskId),
+      userId: n.actorId || n.taskId,
+      type: "text",
+      text: n.content || `[${n.type} on task ${n.title || n.taskId}]`,
+      messageId: id,
+      from: { id: n.actorId, name: n.actorName },
+      spaces: { taskId: n.taskId, spaceId: n.spaceId, notificationType: n.type, deepLink: n.deepLink, title: n.title, mode: this._taskLoopMode() },
+      raw: payload,
+    };
+    // Per-task serialization: a task's turns run one at a time so two comments
+    // on the same task can't spawn concurrent, conflicting agent runs. Other
+    // tasks proceed in parallel.
+    this._deliverSerialized(n.taskId, envelope);
+  }
+
+  // Chain each task's message delivery onto that task's tail promise, so the
+  // next queued event for the same task waits for the current turn to finish.
+  _deliverSerialized(taskId, envelope) {
+    const key = String(taskId);
+    const prev = this._taskChains.get(key) || Promise.resolve();
+    const next = prev
+      .then(() => this._deliverMessage(envelope))
+      .catch((e) => console.error("spaces serialized delivery:", e.message));
+    this._taskChains.set(key, next);
+    next.finally(() => { if (this._taskChains.get(key) === next) this._taskChains.delete(key); });
+  }
+
+  // Await every registered message listener (the router turn resolves when the
+  // agent run completes) so the per-task chain doesn't advance early.
+  async _deliverMessage(envelope) {
+    for (const fn of [...(this._listeners.message || [])]) {
+      try { await fn(envelope); }
+      catch (e) { console.error("spaces message handler:", e.message); }
+    }
+  }
+
+  // send() posts a comment back to the task thread. channelId is
+  // "task:<taskId>"; opts.mentions is an array of {userId,label}; opts.replyTo
+  // threads the reply under a comment id (parentId).
+  async send(channelId, text, opts = {}) {
+    const taskId = String(channelId || "").replace(/^task:/, "");
+    if (!taskId) { console.error("Spaces send: no taskId in channelId", channelId); return null; }
+    try {
+      const comment = await this.client.createComment({
+        taskId,
+        text,
+        mentions: opts.mentions || [],
+        parentId: opts.replyTo ? String(opts.replyTo).replace(/^comment:/, "") : null,
+      });
+      return comment && (comment._id || comment.id) ? String(comment._id || comment.id) : true;
+    } catch (e) {
+      console.error("Spaces send error:", e.message);
+      return null;
+    }
+  }
+
+  // Spaces has no per-thread bot typing indicator, and comment edit/delete are
+  // out of scope for v1. These keep the adapter contract total so core code can
+  // call them unconditionally.
+  async edit() { /* not supported */ }
+  async delete() { /* not supported */ }
+  async typing() { /* no-op */ }
+  async typingStop() { /* no-op */ }
+  async sendVoice() { return false; }
+  async sendPhoto() { return false; }
+  async sendFile() { return false; }
+  async downloadMedia() { return null; }
+  async registerCommands() { /* Spaces has no slash-command registry */ }
+}
+
+module.exports = { SpacesAdapter, ENGAGE_TYPES };

package/channels/spaces/approval-mirror.js

@@ -0,0 +1,52 @@
+// Mirror owner-facing approval activity into the originating Spaces task thread.
+//
+// The BINDING decision always happens on the owner's real button channel
+// (Telegram): Spaces has no inline-button UI, and a task thread can be watched
+// by non-owners, so an external must never hold the Approve button. This posts
+// a NON-binding status comment into the thread so it shows that the bot paused
+// for owner approval and what the owner decided. Best-effort and fully scoped —
+// a no-op unless the approval record's origin is a Spaces task thread.
+
+function isSpacesOrigin(rec) {
+  return !!rec
+    && String(rec.adapter) === "spaces"
+    && String(rec.channelId || "").startsWith("task:");
+}
+
+function spacesAdapter() {
+  try {
+    const registry = require("../../core/adapter-registry");
+    return registry.findAdapter("spaces")
+      || registry.getAdapters().find((a) => a.type === "spaces")
+      || null;
+  } catch (e) { return null; }
+}
+
+async function postComment(rec, text) {
+  const adapter = spacesAdapter();
+  if (!adapter) return false;
+  try { await adapter.send(rec.channelId, text); return true; }
+  catch (e) { console.error("spaces approval-mirror:", e.message); return false; }
+}
+
+async function mirrorRequest(rec) {
+  if (!isSpacesOrigin(rec)) return;
+  const cmd = String(rec.command || "").slice(0, 300);
+  await postComment(rec, [
+    `I need to run a ${rec.tier || "sensitive"} action for this, so I've asked my owner to approve it first:`,
+    "",
+    cmd,
+    "",
+    "I'll update this thread once they decide.",
+  ].join("\n"));
+}
+
+async function mirrorOutcome(rec) {
+  if (!isSpacesOrigin(rec)) return;
+  const label = `${rec.tool || "the action"}${rec.verb ? " " + rec.verb : ""}`;
+  await postComment(rec, rec.status === "approved"
+    ? `My owner approved it — proceeding with ${label}.`
+    : `My owner declined, so I won't run ${label}. Let me know how else I can help.`);
+}
+
+module.exports = { isSpacesOrigin, mirrorRequest, mirrorOutcome };

package/channels/spaces/client.js

@@ -0,0 +1,183 @@
+// Spaces REST client. Thin, dependency-free HTTP over the bot's own opaque
+// token (kzb_…). Endpoints + payload shapes are the ones the `spaces` tool
+// reverse-engineered and has been driving in production — kept in lockstep so
+// this adapter and that tool never diverge. The only difference is auth: the
+// tool logs a human in for a bearer; here the bot presents its own kzb_ token
+// directly (Spaces accepts it — verified via central /api/principal/verify).
+//
+// Everything here is READ-ONLY except createComment (the conversational reply)
+// — the data/awareness plane never mutates Spaces state, so the poller carries
+// no write risk. Notification "seen" tracking is a local cursor, not a
+// server-side mark-read, precisely to keep that plane read-only.
+
+const https = require("https");
+const http = require("http");
+const { URL } = require("url");
+
+function request(baseUrl, token, method, urlPath, body, timeoutMs = 30000) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(baseUrl.replace(/\/$/, "") + urlPath);
+    const lib = u.protocol === "https:" ? https : http;
+    const data = body != null ? Buffer.from(JSON.stringify(body)) : null;
+    const headers = {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/json",
+    };
+    if (data) {
+      headers["Content-Type"] = "application/json";
+      headers["Content-Length"] = data.length;
+    }
+    const req = lib.request(
+      {
+        method,
+        hostname: u.hostname,
+        port: u.port || (u.protocol === "https:" ? 443 : 80),
+        path: u.pathname + (u.search || ""),
+        headers,
+      },
+      (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(`Spaces ${method} ${urlPath} → ${res.statusCode}: ${chunks.slice(0, 300)}`));
+          }
+        });
+      },
+    );
+    req.on("error", reject);
+    req.setTimeout(timeoutMs, () => req.destroy(new Error(`Spaces ${method} ${urlPath} timeout`)));
+    if (data) req.write(data);
+    req.end();
+  });
+}
+
+// Spaces responses are inconsistent: sometimes a bare array, sometimes wrapped
+// in {data|tasks|comments|notifications}. Normalise to an array once here so
+// callers never re-implement the guard.
+function asArray(res, ...keys) {
+  if (Array.isArray(res)) return res;
+  for (const k of keys) {
+    if (res && Array.isArray(res[k])) return res[k];
+  }
+  return (res && (res.data || res.items)) || [];
+}
+
+// Flatten a ProseMirror/TipTap doc (or a JSON string of one, or plain text)
+// down to readable plain text. Mirrors the tool's _flatten/_content_text so a
+// comment body renders the same whether the tool or the adapter reads it.
+function flattenContent(node) {
+  if (node == null) return "";
+  if (typeof node === "string") {
+    const trimmed = node.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+      try { return flattenContent(JSON.parse(trimmed)); }
+      catch (e) { return node; }
+    }
+    return node;
+  }
+  if (Array.isArray(node)) return node.map(flattenContent).join("");
+  if (typeof node !== "object") return String(node);
+  const t = node.type;
+  if (t === "text") return node.text || "";
+  if (t === "mention") return `@${node.attrs?.label || node.attrs?.id || ""}`;
+  if (t === "hardBreak") return "\n";
+  const inner = (node.content || []).map(flattenContent).join("");
+  if (["paragraph", "heading", "listItem", "blockquote"].includes(t)) return inner + "\n";
+  return inner;
+}
+
+function contentText(raw) {
+  return flattenContent(raw).trim();
+}
+
+// Build the stringified ProseMirror doc for an outgoing comment. Optional
+// leading @mention chips (each {userId,label}) drive Spaces' notification
+// fan-out; the tool proved this exact node shape renders as tag chips.
+function buildCommentContent(text, mentions = []) {
+  const inline = [];
+  for (const m of mentions) {
+    inline.push({ type: "mention", attrs: { id: m.userId, label: m.label, mentionSuggestionChar: "@" } });
+    inline.push({ type: "text", text: " " });
+  }
+  if (text) inline.push({ type: "text", text });
+  return JSON.stringify({ type: "doc", content: [{ type: "paragraph", content: inline }] });
+}
+
+class SpacesClient {
+  constructor({ baseUrl = "https://api.spaces.kazee.africa", token }) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.token = token;
+  }
+
+  _get(urlPath, timeoutMs) { return request(this.baseUrl, this.token, "GET", urlPath, null, timeoutMs); }
+  _post(urlPath, body, timeoutMs) { return request(this.baseUrl, this.token, "POST", urlPath, body, timeoutMs); }
+
+  async listTasks() {
+    const res = await this._get("/api/tasks");
+    return asArray(res, "tasks");
+  }
+
+  async getTask(taskId) {
+    const res = await this._get(`/api/tasks/${encodeURIComponent(taskId)}`);
+    return (res && (res.data || res.task)) || res || null;
+  }
+
+  async listComments(taskId, limit = 100) {
+    const res = await this._get(`/api/comments/task/${encodeURIComponent(taskId)}?limit=${limit}`);
+    return asArray(res, "comments");
+  }
+
+  async unreadCount() {
+    const res = await this._get("/api/notifications/unread-count");
+    return typeof res?.count === "number" ? res.count : 0;
+  }
+
+  // Read-only notification fetch. Walks pages, dedupes by id — the Spaces API
+  // sometimes ignores the page param (the tool hit this too), so dedup is not
+  // optional. `unreadOnly` maps to the server-side isRead=false filter.
+  async listNotifications({ limit = 40, unreadOnly = true } = {}) {
+    const out = [];
+    const seen = new Set();
+    let page = 1;
+    while (out.length < limit && page <= 20) {
+      const params = new URLSearchParams({
+        limit: String(Math.min(limit, 100)),
+        page: String(page),
+        offset: String(out.length),
+      });
+      if (unreadOnly) params.set("isRead", "false");
+      const res = await this._get(`/api/notifications?${params.toString()}`);
+      const batch = asArray(res, "notifications");
+      const fresh = batch.filter((n) => {
+        const id = n.id || n._id;
+        return id && !seen.has(String(id));
+      });
+      if (!fresh.length) break;
+      for (const n of fresh) seen.add(String(n.id || n._id));
+      out.push(...fresh);
+      page += 1;
+    }
+    return out.slice(0, limit);
+  }
+
+  // The one write: post a comment back to a task thread. `mentions` is an
+  // array of {userId,label}; `parentId` threads the reply under a comment.
+  async createComment({ taskId, text, mentions = [], parentId = null, attachments = [] }) {
+    const payload = {
+      targetType: "task",
+      targetId: taskId,
+      content: buildCommentContent(text, mentions),
+      attachments: JSON.stringify(attachments),
+      mentions: mentions.map((m) => m.userId),
+    };
+    if (parentId) payload.parentId = parentId;
+    const res = await this._post("/api/comments", payload);
+    return (res && (res.comment || res.data)) || res || null;
+  }
+}
+
+module.exports = { SpacesClient, flattenContent, contentText, buildCommentContent, asArray };

package/channels/spaces/socket.js

@@ -0,0 +1,40 @@
+// Thin wrapper around socket.io-client for Spaces real-time delivery. The
+// Spaces socket auth chain reads the token from handshake.auth.token first
+// (verified in @libraries/inet-central-auth SocketAuthMiddleware), so the bot's
+// kzb_ token goes straight into `auth`, exactly like the Kazee adapter's socket.
+//
+// The one event we care about is the per-user "notification": the server pushes
+// it directly to the recipient's socket (emitToUser → io.to(socketId)), so a
+// Bearer-authed bot receives its own task notifications with no room join.
+// Payload shape (broadcastHandlers.broadcastNotification):
+//   { id, type, title, content, targetType, targetId, spaceId,
+//     actorId, actorName, deepLink, data, timestamp, read }
+
+let io;
+try { io = require("socket.io-client").io; }
+catch (e) { io = null; }
+
+function createSpacesSocket({ url, token, onNotification, onConnect, onDisconnect, onError }) {
+  if (!io) {
+    throw new Error("socket.io-client is not installed. Run `npm install` to install dependencies.");
+  }
+  const socket = io(url, {
+    transports: ["websocket"],
+    auth: { token },
+    reconnection: true,
+    reconnectionDelay: 2000,
+    reconnectionDelayMax: 30000,
+  });
+  socket.on("connect", () => { if (onConnect) onConnect(socket); });
+  socket.on("disconnect", (reason) => { if (onDisconnect) onDisconnect(reason); });
+  socket.on("connect_error", (err) => { if (onError) onError(err); });
+  socket.on("notification", (payload) => {
+    if (onNotification) {
+      try { Promise.resolve(onNotification(payload)).catch((e) => console.error("spaces notification handler:", e.message)); }
+      catch (e) { console.error("spaces notification handler:", e.message); }
+    }
+  });
+  return socket;
+}
+
+module.exports = { createSpacesSocket };