@inetafrica/open-claudia 3.0.22 → 3.0.24

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v3.0.24 — Spaces threads read like a group chat; memory notes go quiet unless you're watching
+
+- **The "🧠 Jotted this down" memory notes are now gated behind `/recall`.** After each turn the pack reviewer still writes to long-term memory exactly as before — but the chat announcement of what it filed away only surfaces when `/recall` is on (`state.settings.showRecall`), the same toggle that already gates the recall/tool banners. Off by default, so ordinary turns stay clean; flip `/recall on` to watch memory (and recall) work. That announcement was the one learning-surface bypassing the gate; it no longer does.
+- **Re-ship of v3.0.23, which never published.** Its tag build failed the version-approval CI gate — `package.json` was bumped without mirroring the assertion in `test-provider-language.js`. Same gate that caught v3.0.21; corrected here as v3.0.24, exactly as v3.0.22 re-shipped v3.0.21.
+- **An engaged Spaces turn now arrives knowing the whole thread, not just one bare comment.** When a tag/reply/assignment engages the bot on a task, the router pulls a **thread-context block** from the adapter and prepends it to the prompt: the task's metadata (title, status/priority/due, assignees, a clipped description) **plus every comment posted since the bot last replied**. So the bot answers like a member who's been reading along, instead of replying blind. The full task + entire comment history stays one `spaces read` tool call away.
+- **"Group chat the bot is a member of."** Untagged comments still never trigger a turn (the engage gate is unchanged — mentions/replies/assignments only). But the next time the bot *is* addressed, everything said in between is caught up in one batched injection. The delta is derived server-side from a per-task **context watermark**, so a missed poll or a restart self-heals — the next engage still pulls the true set. The bot's own prior reply is re-surfaced too, which keeps continuity across auto-compaction.
+- **Bounded by construction.** The catch-up is capped (newest 12 comments, each body clipped) so a busy thread can't blow the prompt; the very first engage on a long-idle task shows recent history, not the entire backlog. Auto-compaction absorbs the rest — no new wiring, it's already per-thread and token-triggered.
+- **Rendered cleanly, not stitched into the message.** Context is delivered via a new channel-agnostic `buildThreadContext()` adapter method that the router renders — `envelope.text` stays pristine, so command detection and the credential scrub are unaffected (the old approach mutated the message text). The seam is generic: Kazee group rooms can implement the same method later, and the since-last-reply delta is exactly the input a future lightweight activation agent would judge to decide whether to chip in unprompted — provisioned, not built.
+- **The bot now leaves a read receipt, like a teammate.** When an engaged turn catches up on a thread, it marks every comment it just read as *seen by* the bot (`comments/mark-seen` → server `$addToSet`s the bot into each comment's `seenBy` and broadcasts `comment:seen`). So a human watching a task sees the bot appear on "seen by" exactly like another member the moment it reads their message — not only when it replies. Fire-and-forget and fully swallowed: it rides the same member/admin `comments.update` scope the reply already uses, and a scope or network failure degrades to silent (never breaks or delays a turn). Only ever fires on an engaged turn — the awareness poll still never mutates Spaces state.
+- **Agent-space / OpenClaw:** no new deps, no new env, no schema change; Docker image builds identically (FROM the pre-baked `:base`). Existing pods pick this up on their next approved upgrade.
+
 ## v3.0.20 — Spaces answers tags, and knows the owner
 
 - **A tag now actually gets a reply.** The Spaces server labels notifications with **plural** categories (`mentions`, `comments`, `reactions`, `task_updated`), but the conversational plane's engage set only matched the singular `mention` — so every real `@`-tag was silently downgraded to awareness-only and the bot never spoke. `ENGAGE_TYPES` now matches the plural forms (`mentions`/`replies`, singular aliases kept for safety). Plain comments, reactions and task updates stay awareness-only, so the "untagged comments hit the radar without auto-answering" rule is unchanged. Confirmed live: a real `mentions` notification was arriving and being dropped.

package/channels/spaces/adapter.js

@@ -30,6 +30,17 @@ const spacesState = require("./state");
 // never auto-reply.
 const ENGAGE_TYPES = new Set(["mention", "mentions", "reply", "replies", "task_assigned"]);
 
+// Description clip length for the front-loaded task context. Long descriptions
+// are deliberately truncated — the agent can pull the full task + comment
+// history on demand via the `spaces` tool's read verb, so we keep the prompt
+// lean instead of pasting a wall of text every turn.
+const TASK_DESC_LIMIT = 800;
+// Catch-up bounds for the "comments since your last reply" block. Cap the count
+// (also bounds the very first engage, which has no watermark) and clip each body
+// so a busy thread can't blow the prompt. Auto-compaction absorbs the rest.
+const CATCHUP_MAX = 12;
+const CATCHUP_BODY_LIMIT = 500;
+
 class SpacesAdapter {
   constructor({ id = "spaces", url = "https://api.spaces.kazee.africa", token, ownerUserId = "", taskLoopMode = "advisory", pollMs }) {
     this.id = id;
@@ -272,7 +283,10 @@ class SpacesAdapter {
   }
 
   // Await every registered message listener (the router turn resolves when the
-  // agent run completes) so the per-task chain doesn't advance early.
+  // agent run completes) so the per-task chain doesn't advance early. Task
+  // context is no longer stitched onto envelope.text here — the router pulls it
+  // via buildThreadContext() and renders it, keeping envelope.text pristine for
+  // command detection and the credential scrub.
   async _deliverMessage(envelope) {
     for (const fn of [...(this._listeners.message || [])]) {
       try { await fn(envelope); }
@@ -280,6 +294,165 @@ class SpacesAdapter {
     }
   }
 
+  // Channel-agnostic thread-context provider (ChannelAdapter contract). The
+  // router calls this on an engaged turn and prepends the returned contextBlock
+  // to the prompt, so the agent arrives on a Spaces thread already knowing what
+  // it's looking at — the task's metadata AND every comment posted since it last
+  // replied — instead of answering blind to one bare comment. Two read-only GETs
+  // (task + comments); any failure returns null so the reply still goes out.
+  //
+  // "Task as a group chat the bot is a member of": untagged comments never fire a
+  // turn (ENGAGE_TYPES gates that), but they're caught up here the next time the
+  // bot IS addressed. The delta is server-derived from a watermark, so a missed
+  // poll or a restart self-heals — the next engage still pulls the true set.
+  //
+  // The same _commentsSince() delta is the exact input a future Haiku activation
+  // agent would judge to decide whether to chip in unprompted — left as a seam,
+  // not built.
+  async buildThreadContext(envelope) {
+    const taskId = envelope?.spaces?.taskId;
+    if (!taskId) return null;
+
+    let task = null;
+    try { task = await this.client.getTask(taskId); }
+    catch (e) { task = null; }
+
+    const lines = ["[Kazee Spaces thread context]"];
+    lines.push(`Task: ${(task && task.title) || envelope.spaces?.title || "(untitled task)"}`);
+
+    if (task && typeof task === "object") {
+      const meta = [];
+      if (task.status) meta.push(`Status: ${task.status}`);
+      if (task.priority) meta.push(`Priority: ${task.priority}`);
+      if (task.dueDate) meta.push(`Due: ${String(task.dueDate).slice(0, 10)}`);
+      if (meta.length) lines.push(meta.join(" · "));
+
+      const people = this._collectPeople(task);
+      if (people.length) lines.push(`Assignees: ${people.join(", ")}`);
+
+      const desc = contentText(task.description || task.content || "");
+      if (desc) {
+        const clipped = desc.length > TASK_DESC_LIMIT
+          ? desc.slice(0, TASK_DESC_LIMIT).trimEnd() + " …[truncated]"
+          : desc;
+        lines.push(`Description: ${clipped}`);
+      }
+    }
+    lines.push(`(Full task + entire comment history on demand: \`spaces\` tool → read --task-id ${taskId}.)`);
+
+    // Catch-up: comments since the bot's last engaged turn, minus the triggering
+    // comment (already the main prompt). Advance the watermark to the newest
+    // comment seen so nothing is re-injected next time.
+    try {
+      const { catchUp, watermark, seenIds } = await this._commentsSince(taskId, envelope.text || "");
+      if (catchUp.length) {
+        lines.push("");
+        lines.push("Comments since your last reply (oldest→newest):");
+        for (const c of catchUp) lines.push(`  [${c.ago}] ${c.who}: ${c.body}`);
+      }
+      if (watermark) { try { spacesState.setContextWatermark(taskId, watermark); } catch (e) {} }
+      // Read receipt: the bot has now read this thread — mark those comments seen
+      // so a human sees the bot on "seen by" like a teammate. Fire-and-forget.
+      if (seenIds && seenIds.length) this._markSeen(taskId, seenIds);
+    } catch (e) { /* catch-up is best-effort; metadata still ships */ }
+
+    const who = envelope.from?.name || "Someone";
+    lines.push("");
+    lines.push(`${who} just commented — reply to this:`);
+
+    return { contextBlock: lines.join("\n") };
+  }
+
+  // Fire-and-forget read-receipt write. Deliberately not awaited by
+  // buildThreadContext: the engaged reply must never wait on it, and any failure
+  // (a scope 403 if the bot token lacks comments.update, a transport blip) is
+  // swallowed. It self-verifies on the first real engage — a persistent 403 in
+  // the logs is the signal that the token needs the comments.update grant.
+  _markSeen(taskId, commentIds) {
+    Promise.resolve()
+      .then(() => this.client.markCommentsSeen({ taskId, commentIds }))
+      .catch((e) => console.error("spaces mark-seen:", e.message));
+  }
+
+  // Read-only comment delta for a task: everything newer than the stored context
+  // watermark, capped and clipped, with the triggering comment (matched by body)
+  // removed so it isn't echoed. Also returns the watermark to advance to (the
+  // newest comment's createdAt). Shared shape so a future activation agent can
+  // reuse it to reason over "what's been said since I last spoke".
+  async _commentsSince(taskId, triggeringText) {
+    let comments = [];
+    try { comments = await this.client.listComments(taskId, 100); }
+    catch (e) { return { catchUp: [], watermark: null, seenIds: [] }; }
+    if (!Array.isArray(comments) || !comments.length) return { catchUp: [], watermark: null, seenIds: [] };
+
+    const ts = (c) => Date.parse(c.createdAt || c.updatedAt || 0) || 0;
+    comments.sort((a, b) => ts(a) - ts(b));
+    const watermark = comments[comments.length - 1].createdAt || null;
+    // Every comment the bot just pulled into this turn is one it has now read —
+    // the id set for the read receipt. The server no-ops the bot's own and
+    // already-seen comments, so passing the whole thread is safe and idempotent.
+    const seenIds = comments.map((c) => c._id || c.id).filter(Boolean).map(String);
+
+    const since = spacesState.getContextWatermark(taskId);
+    const sinceMs = since ? Date.parse(since) || 0 : 0;
+    const trigger = contentText(triggeringText || "").trim();
+
+    const fresh = comments.filter((c) => (sinceMs ? ts(c) > sinceMs : true));
+    const rendered = fresh
+      .map((c) => {
+        const au = c.authorId || c.author || c.userId || {};
+        const who = (typeof au === "object")
+          ? (`${au.firstName || ""} ${au.lastName || ""}`.trim() || au.name || au.email || "?")
+          : String(au || "?");
+        const body = contentText(c.content || "");
+        return { who, body: body.trim(), createdAt: c.createdAt };
+      })
+      .filter((c) => c.body && c.body !== trigger)
+      .map((c) => ({
+        who: c.who,
+        ago: this._ago(c.createdAt),
+        body: c.body.length > CATCHUP_BODY_LIMIT ? c.body.slice(0, CATCHUP_BODY_LIMIT).trimEnd() + " …" : c.body,
+      }));
+
+    // Newest N — a long-idle thread's very first engage shows recent history, not
+    // the entire backlog.
+    const catchUp = rendered.slice(-CATCHUP_MAX);
+    return { catchUp, watermark, seenIds };
+  }
+
+  // Compact relative-time label for a comment timestamp.
+  _ago(iso) {
+    const t = Date.parse(iso || 0);
+    if (!t) return "?";
+    const s = Math.max(0, Math.floor((Date.now() - t) / 1000));
+    if (s < 60) return `${s}s ago`;
+    const m = Math.floor(s / 60);
+    if (m < 60) return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 24) return `${h}h ago`;
+    return `${Math.floor(h / 24)}d ago`;
+  }
+
+  // Gather human-readable names attached to a task, deduped. Spaces uses a
+  // singular `assignee` object plus optional `assignees`/`members`/`participants`
+  // arrays depending on the endpoint, so we defensively merge all of them.
+  _collectPeople(task) {
+    const names = [];
+    const seen = new Set();
+    const add = (u) => {
+      if (!u || typeof u !== "object") return;
+      const full = `${u.firstName || ""} ${u.lastName || ""}`.trim() || u.name || u.email;
+      if (!full) return;
+      const key = String(u.id || u._id || full);
+      if (seen.has(key)) return;
+      seen.add(key);
+      names.push(full);
+    };
+    add(task.assignee);
+    for (const m of (task.assignees || task.members || task.participants || [])) add(m);
+    return names;
+  }
+
   // 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).

package/channels/spaces/client.js

@@ -5,10 +5,14 @@
 // 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.
+// Everything here is READ-ONLY except two writes, both member/admin-tier and
+// both only fired on an ENGAGED turn (never from the awareness poll):
+//   • createComment    — the conversational reply (comments.create).
+//   • markCommentsSeen — the read receipt: marks the thread the bot just read as
+//     seen by the bot, so a human sees it on "seen by" like a teammate
+//     (comments.update; server $addToSets seenBy + broadcasts comment:seen).
+// The awareness/poll plane still never mutates Spaces state — notification "seen"
+// tracking there is a local cursor, not a server-side mark-read.
 
 const https = require("https");
 const http = require("http");
@@ -178,6 +182,23 @@ class SpacesClient {
     const res = await this._post("/api/comments", payload);
     return (res && (res.comment || res.data)) || res || null;
   }
+
+  // The second write: mark a set of task comments as seen by the bot — the read
+  // receipt. The server $addToSets the bot into each comment's seenBy (skipping
+  // ones it already saw or authored) and broadcasts a `comment:seen` socket
+  // event, so a human sees the bot on "seen by" exactly like another teammate.
+  // Needs the comments.update scope — the same member/admin tier the working
+  // createComment already relies on. Best-effort at the call site.
+  async markCommentsSeen({ taskId, commentIds }) {
+    const ids = (Array.isArray(commentIds) ? commentIds : []).map(String).filter(Boolean);
+    if (!ids.length) return null;
+    const res = await this._post("/api/comments/mark-seen", {
+      targetType: "task",
+      targetId: taskId,
+      commentIds: ids,
+    });
+    return res || null;
+  }
 }
 
 module.exports = { SpacesClient, flattenContent, contentText, buildCommentContent, asArray };

package/channels/spaces/state.js

@@ -92,6 +92,27 @@ function getCursor(taskId) {
   return s.tasks[String(taskId || "")] || null;
 }
 
+// Context watermark: the createdAt (ISO) of the newest comment the bot has
+// already folded into an engaged turn for this task. buildThreadContext reads
+// it to compute the "comments since my last reply" delta and advances it after
+// each engage, so the same comment is never re-injected. Distinct from the
+// notification cursor above (which tracks awareness activity, not turn context).
+function setContextWatermark(taskId, iso) {
+  const id = String(taskId || "");
+  if (!id || !iso) return;
+  const s = load();
+  const cur = s.tasks[id] || { count: 0 };
+  cur.contextAt = String(iso);
+  s.tasks[id] = cur;
+  save();
+}
+
+function getContextWatermark(taskId) {
+  const s = load();
+  const t = s.tasks[String(taskId || "")];
+  return (t && t.contextAt) || null;
+}
+
 // Mark that a task has had an agent turn emitted for it (from any source: a
 // socket/poll notification OR the reconciliation poll). The reconciliation poll
 // reads this to avoid re-engaging a task the socket already handled — dedup is
@@ -212,7 +233,8 @@ function controlSnapshot() {
 }
 
 module.exports = {
-  markProcessed, recordCursor, getCursor, markTaskEngaged, taskEngaged, snapshot, STATE_FILE,
+  markProcessed, recordCursor, getCursor, setContextWatermark, getContextWatermark,
+  markTaskEngaged, taskEngaged, snapshot, STATE_FILE,
   markSocketConnected, markRestConnected, setCentralConnected, isConnected,
   setMuted, setTaskLoopMode, taskLoopMode, conversationalActive, controlSnapshot,
 };

package/core/handlers.js

@@ -1055,7 +1055,7 @@ register({
     }
     send(
       `Recall debug: ${settings.showRecall ? "on" : "off"}\n\n` +
-      "When on, I post a short \"🧠 Recall this turn\" line before each reply, showing which packs/entities surfaced (and, on the discoverer engine, why). Lets you watch recall work.",
+      "When on, I post a short \"🧠 Recall this turn\" line before each reply, showing which packs/entities surfaced (and, on the discoverer engine, why), plus the \"🧠 Jotted this down\" notes whenever I update long-term memory. When off, recall and memory-writes still happen — you just don't see the banners.",
       { keyboard: { inline_keyboard: [
         [{ text: "On", callback_data: "rcl:on" }, { text: "Off", callback_data: "rcl:off" }],
       ] } },

package/core/router.js

@@ -456,6 +456,24 @@ async function handleText(envelope) {
     }
   }
 
+  // Thread-membership context. Multi-participant thread surfaces (Kazee Spaces
+  // tasks today; Kazee group rooms later) can supply a context block — thread
+  // metadata plus any messages posted since the bot last replied — so an
+  // engaged turn arrives knowing the whole thread, not just the one triggering
+  // message. The adapter owns WHAT to fetch; the router owns WHEN and HOW to
+  // render it. Channels without the method (Telegram, Kazee DM, voice, web) are
+  // untouched. Best-effort: a failure never blocks the turn.
+  if (typeof envelope.adapter?.buildThreadContext === "function") {
+    try {
+      const threadCtx = await envelope.adapter.buildThreadContext(envelope);
+      if (threadCtx && threadCtx.contextBlock) {
+        prompt = `${threadCtx.contextBlock}\n\n${prompt}`;
+      }
+    } catch (e) {
+      console.error("router: buildThreadContext:", e.message);
+    }
+  }
+
   return runAgent(prompt, runContext.cwd, envelope.messageId, {
     runContext,
     imagePaths,

package/core/runner.js

@@ -1836,9 +1836,12 @@ function createForegroundService({ state, store, stopTyping, capture, ownsAdmiss
   return service;
 }
 
-async function handoffMemoryReview(result, runContext, store) {
+async function handoffMemoryReview(result, runContext, store, state) {
   if (!result.ok || !result.text || runContext.purpose !== "foreground") return;
   const recall = result.recallMetadata || {};
+  // Memory is always written; the chat announcement of what was jotted is a
+  // /recall-gated debug surface — silent unless the owner turned recall on.
+  const showRecall = !!state?.settings?.showRecall;
   packReview.reviewTurn({
     userText: runContext.userPrompt,
     assistantText: result.text,
@@ -1853,7 +1856,7 @@ async function handoffMemoryReview(result, runContext, store) {
         return speaker ? { name: speaker.name, isOwner: !!speaker.isOwner } : null;
       } catch (_) { return null; }
     })(),
-    announce: (text) => chatContext.run(store, () => send(text)),
+    announce: showRecall ? (text) => chatContext.run(store, () => send(text)) : null,
   });
 }
 
@@ -1916,7 +1919,7 @@ async function executeAdmittedRun(runContext, state, store, capture, ownsAdmissi
   if (!capture && service.turnObserver && runContext.purpose === "foreground") {
     try { service.turnObserver.onTurnSettled(!!result.ok); } catch (e) { /* best-effort */ }
   }
-  if (!internalCapture) await handoffMemoryReview(result, runContext, store);
+  if (!internalCapture) await handoffMemoryReview(result, runContext, store, state);
   if (!internalCapture && state.settings?.backend === runContext.provider && state.settings.budget) {
     state.settings.budget = null;
     try { saveState({ strict: true }); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "3.0.22",
+  "version": "3.0.24",
   "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,18 +32,16 @@ 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.22 approved by Sumeet 2026-07-14 ("Yeh push out"): per-thread conversations
-// + Spaces output hygiene. The live conversation now keys by THREAD
-// (transport:channelId via currentConversationKey off AsyncLocalStorage) instead
-// of by canonical identity alone, so Telegram DM and each Spaces task get isolated
-// sessions/transcripts while memory + guardrails + soul stay one global brain.
-// seedConversationContinuity does a one-time non-destructive COPY of the legacy
-// "Workspace" session/usage/history into the home conversationKey (anchored by
-// canonical match; secondary channels start clean). turn-observer suppresses the
-// Spaces <b> banner + tool-trace leak. 3.0.21 shipped the same work but its CI
-// build failed on THIS gate (package.json bumped without the assertion) — nothing
-// published under 3.0.21; 3.0.22 is the corrected re-ship.
-assert.strictEqual(pkg.version, "3.0.22", "release version must remain unchanged without explicit approval");
+// 3.0.24 approved by Sumeet 2026-07-14: turn-context add-on (an engaged Spaces
+// turn gets task metadata + every comment since the bot's last reply, via the
+// channel-agnostic buildThreadContext() adapter seam the router prepends) PLUS
+// /recall now gates the "🧠 Jotted this down" memory-write announcements — memory
+// still writes every turn, the chat note only surfaces when /recall is on
+// (state.settings.showRecall), matching how the recall/tool banners already gate.
+// 3.0.23 shipped the turn-context work but its CI build failed on THIS gate
+// (package.json bumped without updating the assertion) — nothing published under
+// 3.0.23; 3.0.24 is the corrected re-ship (same pattern as 3.0.21 → 3.0.22).
+assert.strictEqual(pkg.version, "3.0.24", "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}`);
 }