@inetafrica/open-claudia 3.0.15 → 3.0.16

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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,224 @@
+// 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 = "", conversational = true, taskLoopMode = "advisory" }) {
+    this.id = id;
+    this.type = "spaces";
+    this.url = url.replace(/\/$/, "");
+    this.token = token;
+    this.ownerUserId = ownerUserId || "";
+    this.conversational = conversational;
+    this.taskLoopMode = 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 || "");
+  }
+
+  // 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;
+
+    // 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.
+    const engage = this.conversational && 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 };

package/channels/spaces/state.js

@@ -0,0 +1,76 @@
+// 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) || {};
+  store = {
+    processed: Array.isArray(raw.processed) ? raw.processed.slice(-PROCESSED_CAP) : [],
+    tasks: raw.tasks && typeof raw.tasks === "object" ? raw.tasks : {},
+  };
+  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 };
+}
+
+module.exports = { markProcessed, recordCursor, getCursor, snapshot, STATE_FILE };

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. Gated by OC_SPACES_CONVERSATIONAL so
+  // this has zero effect unless the conversational plane is deliberately on.
+  try {
+    if (currentTransport() === "spaces"
+      && require("./project-transcripts").truthy(config.OC_SPACES_CONVERSATIONAL || process.env.OC_SPACES_CONVERSATIONAL, false)) {
+      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,34 @@ 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 || "",
+          // Two independent gates: constructing the adapter (CHANNELS includes
+          // spaces) starts the socket for awareness; conversational (this flag,
+          // default OFF) is what lets a mention/reply actually run an agent
+          // turn. Keeps auto-replies behind a deliberate opt-in.
+          conversational: configTruthy(config.OC_SPACES_CONVERSATIONAL || process.env.OC_SPACES_CONVERSATIONAL, false),
+          // Task-working posture for engaged Spaces turns: "advisory" (default —
+          // read/reason/recommend, no autonomous write chains), "autonomous"
+          // (work to completion; writes still hit the owner-approval gate), or
+          // "off". Only shapes the agent's framing; approval safety is separate.
+          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) {
@@ -305,6 +337,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,223 @@
+// 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);
+    }
+  }
+  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/loopback.js

@@ -520,6 +520,32 @@ async function handleJson(req, res, url, kind) {
         }
       } catch (e) { /* if classification fails, fall through — approvals stay owner-scoped by the apr: handler's isChatOwner gate */ }
       const approvals = require("./approvals");
+      // Spaces-origin runs: Spaces has no inline-button UI and its thread can be
+      // watched by non-owners, so the BINDING Approve/Deny goes to the owner's
+      // real button channel (Telegram) while the task thread gets a non-binding
+      // status mirror. Origin (channelId/adapter) still records the Spaces thread
+      // so a detached re-run wakes the agent back on the task. Gated by
+      // OC_SPACES_CONVERSATIONAL — off ⇒ byte-identical to the legacy path.
+      const { config: cfg } = require("./config");
+      let buttonAdapter = adapter;
+      let buttonChannel = channelId;
+      let approverAdapter = "";
+      let approverChannel = "";
+      const spacesOrigin = adapter.type === "spaces"
+        && require("./project-transcripts").truthy(cfg.OC_SPACES_CONVERSATIONAL || process.env.OC_SPACES_CONVERSATIONAL, false);
+      if (spacesOrigin) {
+        const owner = require("./relationship").ownerTarget();
+        const oa = owner
+          ? (registry.findAdapter(owner.adapter) || registry.getAdapters().find((a) => a.type === owner.adapter))
+          : null;
+        if (!owner || !oa) {
+          return reply(res, 503, { error: "no reachable owner channel to bind the approval — run stays blocked" });
+        }
+        buttonAdapter = oa;
+        buttonChannel = owner.channelId;
+        approverAdapter = owner.adapter;
+        approverChannel = owner.channelId;
+      }
       const rec = approvals.create({
         tool: payload.tool, verb: payload.verb || "", tier: payload.tier || "destructive",
         command: payload.command, channelId, adapter: adapterId,
@@ -532,9 +558,11 @@ async function handleJson(req, res, url, kind) {
         sessionId: payload.sessionId || null,
         previousSessionId: payload.previousSessionId || null,
         originRunId: payload.originRunId || null,
+        approverAdapter,
+        approverChannel,
       });
       const text = [
-        `🔐 Destructive tool run wants approval:`,
+        `🔐 Destructive tool run wants approval${spacesOrigin ? " (from a Spaces task)" : ""}:`,
         ``,
         `<pre>${String(rec.command).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")}</pre>`,
         ``,
@@ -547,11 +575,15 @@ async function handleJson(req, res, url, kind) {
       ]] };
       // <pre> needs Telegram's HTML parse mode to render; other adapters ignore it.
       const sendOpts = { keyboard };
-      if (adapter.type === "telegram") sendOpts.parseMode = "HTML";
+      if (buttonAdapter.type === "telegram") sendOpts.parseMode = "HTML";
       const { normalizeSendResult } = require("./io");
-      const sent = normalizeSendResult(await adapter.send(channelId, text, sendOpts));
+      const sent = normalizeSendResult(await buttonAdapter.send(buttonChannel, text, sendOpts));
       if (!sent.ok) { approvals.decide(rec.id, "denied", "send-failed"); return reply(res, 500, { error: "could not deliver approval prompt" }); }
-      audit.log("tool.approval.requested", { id: rec.id, tool: rec.tool, verb: rec.verb, channelId });
+      // Non-binding status comment into the originating Spaces thread.
+      if (spacesOrigin) {
+        try { await require("../channels/spaces/approval-mirror").mirrorRequest(rec); } catch (e) {}
+      }
+      audit.log("tool.approval.requested", { id: rec.id, tool: rec.tool, verb: rec.verb, channelId, approver: approverChannel || channelId });
       return reply(res, 200, { ok: true, id: rec.id });
     } catch (e) { return reply(res, 400, { error: e.message }); }
   }

package/core/system-prompt.js

@@ -767,6 +767,36 @@ function buildExternalModeBlock() {
   return lines.join("\n");
 }
 
+// Advisory framing for the Spaces conversational plane. When the current turn
+// is on a Kazee Spaces task thread and the task loop is in its default ADVISORY
+// mode, this reminds the agent to work the task as an advisor — read, reason,
+// and reply with analysis / a recommendation / a clarifying question — rather
+// than silently executing long chains of writes. It RIDES THE TAIL (never the
+// cached, owner-agnostic core instructions) and is GUIDANCE; the binding control
+// is still the per-write approval gate, which for a Spaces-origin action posts
+// its buttons to the owner's Telegram. No-op ("") on every non-Spaces transport.
+function buildSpacesTaskModeBlock() {
+  let transport;
+  try { transport = require("./context").currentTransport(); } catch (e) { transport = ""; }
+  if (transport !== "spaces") return "";
+  const mode = String(config.OC_SPACES_TASK_LOOP ?? process.env.OC_SPACES_TASK_LOOP ?? "advisory").toLowerCase();
+  if (mode === "off") return "";
+  if (mode === "autonomous") {
+    return [
+      "\n\n## Spaces task — autonomous mode",
+      "You're engaged on a Kazee Spaces task thread. You may work the task through to completion, but every write or destructive action still goes through the owner-approval gate, and approvals bind on the owner's Telegram button — never on a Spaces comment. Reply in-thread with concise progress and post a clear result when done.",
+    ].join("\n");
+  }
+  return [
+    "\n\n## Spaces task — advisory mode",
+    "You're engaged on a Kazee Spaces task thread. Work it as an ADVISOR by default:",
+    "- Read the task and its comments, reason about it, and reply in-thread with your analysis, a recommendation, or a clarifying question.",
+    "- Do NOT autonomously run long chains of write/destructive actions to \"just do it\" — surface a short plan and let the owner drive execution.",
+    "- Any single write you do attempt still goes through the normal approval gate, and approvals bind on the owner's Telegram button, never on a Spaces comment.",
+    "- Keep replies tight and thread-appropriate; this is a shared work surface, not a private chat.",
+  ].join("\n");
+}
+
 // The composed prompt can carry text the user didn't write this turn:
 // router.js wraps Telegram reply-quotes in "Replying to …:\n---\n…\n---",
 // and quoting a 📖 recall announcement echoes every entity named in it.
@@ -985,6 +1015,7 @@ function createPromptBuilder(dependencies = {}) {
       const runtimeContext = mandatoryPromptPart("runtimeContext", () => runtimeBuilder({ ...opts, state }));
       const speakerContext = mandatoryPromptPart("speakerContext", () => speakerBuilder({ ...opts, state }));
       const relationshipContext = mandatoryPromptPart("relationshipContext", () => relationshipBuilder({ ...opts, state }));
+      const spacesTaskMode = mandatoryPromptPart("spacesTaskMode", () => buildSpacesTaskModeBlock({ ...opts, state }));
       const transcriptContext = mandatoryPromptPart("transcriptContext", () => transcriptPointerNoteForRun(opts.runContext, state));
       const speakerPersona = mandatoryPromptPart("speakerPersona", () => buildSpeakerPersonaBlock({ ...opts, state }));
       const voiceContext = mandatoryPromptPart("voiceContext", () => voiceReplyGuidance({ ...opts, state }));
@@ -1031,6 +1062,7 @@ function createPromptBuilder(dependencies = {}) {
         recallResult.dynamicContext,
         voiceContext,
         relationshipContext,
+        spacesTaskMode,
       ].filter((part) => typeof part === "string" && part.trim()).join("\n\n");
 
       return {
@@ -1061,6 +1093,7 @@ module.exports = {
   buildOptionalRecallContext,
   buildDynamicContextBlock,
   buildExternalModeBlock,
+  buildSpacesTaskModeBlock,
   buildSpeakerContextBlock,
   buildSpeakerPersonaBlock,
   buildSystemPrompt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "3.0.15",
+  "version": "3.0.16",
   "description": "An always-on, provider-agnostic coding-agent harness for Claude Code and OpenAI Codex via chat",
   "main": "bot.js",
   "bin": {

package/test-provider-language.js

@@ -32,11 +32,12 @@ assert.doesNotMatch(setup, /Your Claude Code bot is connected|Description=Claude
 
 const pkg = JSON.parse(read("package.json"));
 assert.match(pkg.description, /provider-agnostic coding-agent harness/i);
-// 3.0.15 approved by Sumeet 2026-07-14 ("Yes fix and push"): episodic-recall
-// owner gate now resolves the speaker by canonical user id (not raw channelId),
-// so the owner keeps cross-conversation episodic memory on Kazee / group chats
-// where channelId is a room id that never matches the stored user-id handle.
-assert.strictEqual(pkg.version, "3.0.15", "release version must remain unchanged without explicit approval");
+// 3.0.16 approved by Sumeet 2026-07-14 ("I want to upgrade and test"): the
+// Spaces connected-apps task-working loop (advisory) and the approval
+// thread-mirror ship dormant behind the existing OFF flags (OC_CONNECTED_APPS,
+// OC_SPACES_CONVERSATIONAL, OC_SPACES_TASK_LOOP=advisory) — no behaviour change
+// on Telegram/Kazee until a flag is flipped and the bot is a Spaces member.
+assert.strictEqual(pkg.version, "3.0.16", "release version must remain unchanged without explicit approval");
 for (const keyword of ["claude", "codex", "coding-agent", "provider-agnostic"]) {
   assert.ok(pkg.keywords.includes(keyword), `package keyword missing: ${keyword}`);
 }