@inetafrica/open-claudia 3.5.0 → 3.5.4

package/core/handlers.js

@@ -20,8 +20,10 @@ const {
   getProviderSettings, resolveProviderSettings,
   getProjectSessions, getLastProjectSession, userOwnsProviderSession,
   createSessionCallbackToken, linkIdentity,
-  roomSettingsFor, setRoomSetting, cancelFlagFor,
+  roomSettingsFor, setRoomSetting, cancelFlagFor, activeRoomKey,
+  laneFor, peekLane, runningLanes, laneBusy, currentLaneKey,
 } = require("./state");
+const { parseConversationKey } = require("./identity");
 const { canonicalForChannel, canonicalForTelegram, normalizeCanonicalUserId, channelKey, identities, isConfiguredOwnerChannel, removeIdentityMapping } = require("./identity");
 const { isChatAuthorized, isChatOwner, recordPendingAuthRequest, authRequestLabel, hasOwner, bootstrapOwner } = require("./access");
 const { isOnboarded, startOnboarding } = require("./onboarding");
@@ -85,12 +87,25 @@ function cancelledQueueResult(item, reason) {
   };
 }
 
-function clearTransientQueue(state, reason = "Session context changed before the queued run started") {
-  const queued = Array.isArray(state?.messageQueue) ? state.messageQueue.splice(0) : [];
+// Drops every message queued in one lane: each one's caller gets a cancelled
+// result (no hanging promise), and an idle lane loses its typing heartbeat (the
+// chip would stay on, and the lane could never be pruned). Returns the items.
+function dropLaneQueue(lane, reason) {
+  if (!lane) return [];
+  const queued = lane.messageQueue.splice(0);
+  lane.waitingForSlot = false;
   for (const item of queued) {
+    try { item?.disposeCallListener?.(); } catch (_) {}
     try { item?.deferred?.resolve(cancelledQueueResult(item, reason)); } catch (_) {}
   }
-  return queued.length;
+  if (!laneBusy(lane)) require("./runner").stopLaneTyping(lane);
+  return queued;
+}
+
+// Clears the CURRENT conversation's queue only: /new, /end or a project change
+// in one thread must not drop what another conversation has waiting.
+function clearTransientQueue(state, reason = "Session context changed before the queued run started") {
+  return dropLaneQueue(state ? peekLane(state) : null, reason).length;
 }
 
 function persistSessionControl(state, options, rollback) {
@@ -216,7 +231,7 @@ function switchProviderState(providerId, options = {}) {
   // stays updated as their default for rooms they have never pinned. Without
   // the room write, switching provider only moved the switcher — everyone else
   // in the room, and every job it spawned, stayed on the old one.
-  const roomKey = state.roomKey ? String(state.roomKey) : "";
+  const roomKey = activeRoomKey() || "";
   const previousRoomBackend = roomKey ? (roomSettingsFor(roomKey)?.backend ?? null) : null;
   if (roomKey) setRoomSetting(roomKey, "backend", provider);
   state.settings.backend = provider;
@@ -297,7 +312,8 @@ function endCurrentSession(options = {}) {
   clearTransientQueue(state, "The conversation ended before the queued run started");
   state.currentSession = rootSession();
   state.isFirstMessage = true;
-  state.cancelRequested = false;
+  const lane = peekLane(state);
+  if (lane) lane.cancelRequested = false;
   const persisted = persistSessionControl(state, options, () => {
     state.currentSession = previous.currentSession;
     state.isFirstMessage = previous.isFirstMessage;
@@ -1413,10 +1429,10 @@ register({
     if (arg) {
       const low = arg.toLowerCase();
       if (low === "clone") {
-        state.pendingVoiceClone = { at: Date.now() };
+        laneFor(state).pendingVoiceClone = { at: Date.now() };
         return send("🎙️ Send me a voice note now — 5–15s of clear speech and I'll clone it as your voice. Send /voice to cancel.");
       }
-      state.pendingVoiceClone = null;
+      laneFor(state).pendingVoiceClone = null;
       if (low === "default" || low === "reset") {
         ttsVoice.clearVoice();
         return send(`🎙️ Voice reset to default (${ttsVoice.getVoiceLabel()}).`);
@@ -1431,7 +1447,7 @@ register({
       ttsVoice.setVoice(arg, null);
       return send(`🎙️ Voice set: ${arg}`);
     }
-    state.pendingVoiceClone = null;
+    laneFor(state).pendingVoiceClone = null;
     const rows = ttsVoice.presets().map((p) => [{ text: p.label, callback_data: `vc:p:${p.key}` }]);
     rows.push([
       { text: "🎙️ Clone from a clip", callback_data: "vc:clone" },
@@ -1643,63 +1659,148 @@ register({
 });
 
 // How long /stop waits for a stopped child to report its exit before it
-// releases the room anyway (SIGKILL follows SIGTERM after 3 s).
+// releases the conversation anyway (SIGKILL follows SIGTERM after 3 s).
 const STOP_RELEASE_MS = 30 * 1000;
-function releaseStuckStop(state, proc, stopped) {
-  if (state.runningProcess !== proc) return;
-  if (proc.exitCode != null || proc.signalCode != null) return; // exited: its unwind releases the room
-  console.warn(`[stop] child ${proc.pid} never reported its exit; releasing the room`);
-  state.runningProcess = null;
-  if (state.cancelRequested === stopped) state.cancelRequested = false;
+function releaseStuckStop(state, lane, proc, stopped) {
+  if (lane.runningProcess !== proc) return;
+  if (proc.exitCode != null || proc.signalCode != null) return; // exited: its unwind releases the lane
+  console.warn(`[stop] child ${proc.pid} never reported its exit; releasing the conversation`);
+  lane.runningProcess = null;
+  lane.ownerToken = null;
+  if (lane.cancelRequested === stopped) lane.cancelRequested = false;
+  try { require("./runner").drainQueuedMessages(state); } catch (_) {}
+}
+
+// Stop one lane's turn. Same kill semantics as a single /stop always had:
+// SIGTERM the tree now, SIGKILL after 3 s, keep the lane busy until the run
+// unwinds (its own finally frees it and admits what waits). Returns what was
+// stopped: "running", "preparing", or null when the lane had nothing to stop.
+function stopLane(state, lane) {
+  const { stopLaneTyping } = require("./runner");
+  if (lane.runningProcess && !lane.activeRunContext) {
+    // Only a compaction runs here (a /compact, or the auto-compaction tail of
+    // a turn that already answered). Kill it and let it fail on its own; a
+    // bare cancel flag would outlive it and silently eat the next message.
+    const pid = lane.runningProcess.pid;
+    const { killProcessTree } = require("./process-tree");
+    killProcessTree(pid, "SIGTERM");
+    setTimeout(() => killProcessTree(pid, "SIGKILL"), 3000);
+    stopLaneTyping(lane);
+    return "running";
+  }
+  if (lane.runningProcess) {
+    const proc = lane.runningProcess;
+    const pid = proc.pid;
+    const { killProcessTree } = require("./process-tree");
+    // Quiet unwind: deliverForegroundResult consumes this flag to suppress
+    // the "run failed" diagnostic the SIGTERM exit would otherwise emit. It
+    // names the run it stops, so it can never cancel a different one.
+    const stopped = cancelFlagFor(lane);
+    lane.cancelRequested = stopped;
+    killProcessTree(pid, "SIGTERM");
+    setTimeout(() => killProcessTree(pid, "SIGKILL"), 3000);
+    // The lane stays busy until the stopped run has unwound: its own finally
+    // releases it, clears this flag and admits the queue. Releasing it here
+    // let a message sent in those seconds start, meet the flag and be
+    // cancelled "before the provider started" (24 Sep: three messages lost
+    // after one /stop). Backstop: a child that never reports its exit must
+    // not pin the conversation.
+    setTimeout(() => releaseStuckStop(state, lane, proc, stopped), STOP_RELEASE_MS).unref?.();
+    // Stop pending preview flushes but keep statusMessageId/Channel: the
+    // killed run's delivery unwind edits the preview to drop its footer.
+    if (lane.streamInterval) { clearTimeout(lane.streamInterval); lane.streamInterval = null; }
+    // Clearing the heartbeat here orphans the run's own stopper (ownership
+    // check makes it a no-op), so the explicit typing:stop must go out now.
+    stopLaneTyping(lane);
+    return "running";
+  }
+  if (lane.preparingRun) {
+    // Turn is mid-recall/prompt-build — no process to kill yet. Flag it so
+    // the runner's pre-spawn shouldAbort checkpoint bails before spawning.
+    lane.cancelRequested = cancelFlagFor(lane);
+    stopLaneTyping(lane);
+    return "preparing";
+  }
+  return null;
+}
+
+const STOP_DROP_REASON = "Dropped by /stop before it started";
+
+// "Dropped 2 queued: "reboot pe2", "and check the…"": what /stop dropped, a
+// few words of each message (the first few in full, then a count).
+function droppedNote(items, kind) {
+  const words = (item) => {
+    const all = String(item?.text || item?.runContext?.userPrompt || item?.pendingSideChat?.originalRunContext?.userPrompt || "").replace(/\s+/g, " ").trim().split(" ").filter(Boolean);
+    const head = all.slice(0, 3).join(" ");
+    const short = head.length > 24 ? `${head.slice(0, 23)}…` : (all.length > 3 ? `${head}…` : head);
+    return `"${short || "…"}"`;
+  };
+  const n = items.length;
+  const shown = items.slice(0, 3).map(words);
+  if (n > shown.length) shown.push(`+${n - shown.length} more`);
+  const label = kind === "waiting"
+    ? `${n} waiting message${n === 1 ? "" : "s"}`
+    : `${n} queued`;
+  return `Dropped ${label}: ${shown.join(", ")}`;
+}
+
+// A few words about a conversation: main timeline or which thread, and what
+// its turn is about.
+function describeLane(lane, currentRoom = null) {
+  const { threadId, roomKey } = parseConversationKey(lane.key);
+  const where = `${threadId ? `thread …${threadId.slice(-6)}` : "main"}${currentRoom && roomKey !== currentRoom ? ` (${roomKey})` : ""}`;
+  const words = String(lane.activeRunContext?.userPrompt || "")
+    .replace(/\s+/g, " ").trim().split(" ").slice(0, 6).join(" ");
+  const what = lane.isCompacting ? "compacting" : (words ? `"${words.length > 48 ? `${words.slice(0, 47)}…` : words}"` : "working");
+  return `${where}: ${what}`;
+}
+
+function runningConversationLines(state) {
+  const lanes = runningLanes(state);
+  const waiting = state.lanes instanceof Map
+    ? [...state.lanes.values()].filter((lane) => !laneBusy(lane) && lane.messageQueue.length).length
+    : 0;
+  if (!lanes.length && !waiting) return [];
+  return [
+    `Running conversations: ${lanes.length}${waiting ? ` (${waiting} waiting for a slot)` : ""}`,
+    ...lanes.map((lane) => `- ${describeLane(lane, parseConversationKey(currentLaneKey(state)).roomKey)}`),
+  ];
 }
 
 register({
-  name: "stop", description: "Cancel running task",
-  handler: async (env) => {
+  name: "stop", description: "Cancel the running task here (/stop all: every conversation)", args: "[all]",
+  handler: async (env, { tail } = {}) => {
     if (!authorized(env)) return;
     const state = currentState();
-    const sideCancellation = require("./side-chat").sideChatCoordinator.cancel(state.userId);
-    // /stop cancels the CURRENT turn only. Messages queued behind it stay
-    // queued — the cancelled run's unwind drains them as usual.
-    const queuedNote = () => {
-      const n = Array.isArray(state.messageQueue) ? state.messageQueue.length : 0;
-      return n ? ` ${n} queued message${n === 1 ? "" : "s"} will run next.` : "";
-    };
-    if (state.runningProcess) {
-      const proc = state.runningProcess;
-      const pid = proc.pid;
-      const { killProcessTree } = require("./process-tree");
-      // Quiet unwind: deliverForegroundResult consumes this flag to suppress
-      // the "run failed" diagnostic the SIGTERM exit would otherwise emit. It
-      // names the run it stops, so it can never cancel a different one.
-      const stopped = cancelFlagFor(state);
-      state.cancelRequested = stopped;
-      killProcessTree(pid, "SIGTERM");
-      setTimeout(() => killProcessTree(pid, "SIGKILL"), 3000);
-      // The room stays busy until the stopped run has unwound: its own
-      // finally releases the lock, clears this flag and drains the queue.
-      // Releasing it here let a message sent in those seconds start, meet the
-      // flag and be cancelled "before the provider started" (24 Sep: three
-      // messages lost after one /stop). Backstop: a child that never reports
-      // its exit must not pin the room.
-      setTimeout(() => releaseStuckStop(state, proc, stopped), STOP_RELEASE_MS).unref?.();
-      // Stop pending preview flushes but keep statusMessageId/Channel: the
-      // killed run's delivery unwind edits the preview to drop its footer.
-      if (state.streamInterval) { clearTimeout(state.streamInterval); state.streamInterval = null; }
-      // Clearing the interval here orphans the run's own stopper (ownership
-      // check makes it a no-op), so the explicit typing:stop must go out now.
-      if (state.typingHeartbeat) { clearInterval(state.typingHeartbeat); state.typingHeartbeat = null; state.thinkingPhase = false; state.typingTick = null; }
-      try { currentAdapter()?.typingStop?.(currentChannelId()); } catch (_) {}
+    const { sideChatCoordinator } = require("./side-chat");
+    if (String(tail || "").trim().toLowerCase() === "all") {
+      const sideCancellation = sideChatCoordinator.cancel(state.userId);
+      const lanes = state.lanes instanceof Map ? [...state.lanes.values()] : [];
+      // Drop the queues first, so no stopped lane's unwind admits them.
+      const dropped = lanes.flatMap((lane) => dropLaneQueue(lane, STOP_DROP_REASON));
+      const stopped = lanes.filter((lane) => stopLane(state, lane)).length;
+      const sideStopped = await sideCancellation;
+      if (!stopped && !dropped.length) return send(sideStopped ? "Cancelled side response." : "Nothing running.");
+      const parts = [];
+      if (stopped) parts.push(`Cancelled ${stopped} running conversation${stopped === 1 ? "" : "s"}.`);
+      if (dropped.length) parts.push(droppedNote(dropped, stopped ? "queued" : "waiting"));
+      return send(parts.join(" "));
+    }
+    // /stop cancels the CURRENT conversation's turn only (other threads keep
+    // running) and drops what was queued in it before the /stop: the person
+    // meant "stop", not "stop this one and start the next". A message sent
+    // after the /stop still queues behind the unwinding run and then runs.
+    const lane = laneFor(state);
+    const sideCancellation = sideChatCoordinator.cancel(state.userId, lane.key);
+    const dropped = dropLaneQueue(lane, STOP_DROP_REASON);
+    if (stopLane(state, lane)) {
       await sideCancellation;
-      await send(`Cancelled.${queuedNote()}`);
-    } else if (state.preparingRun) {
-      // Turn is mid-recall/prompt-build — no process to kill yet. Flag it so
-      // the runner's pre-spawn shouldAbort checkpoint bails before spawning.
-      state.cancelRequested = cancelFlagFor(state);
-      if (state.typingHeartbeat) { clearInterval(state.typingHeartbeat); state.typingHeartbeat = null; state.thinkingPhase = false; state.typingTick = null; }
-      try { currentAdapter()?.typingStop?.(currentChannelId()); } catch (_) {}
+      await send(dropped.length ? `Cancelled. ${droppedNote(dropped, "queued")}` : "Cancelled.");
+    } else if (dropped.length) {
+      // Nothing to cancel: the dropped messages were waiting for a slot (or
+      // queued behind a turn that is only finishing its tail).
       await sideCancellation;
-      await send(`Cancelled.${queuedNote()}`);
+      await send(droppedNote(dropped, laneBusy(lane) ? "queued" : "waiting"));
     } else if (await sideCancellation) await send("Cancelled side response.");
     else await send("Nothing running.");
   },
@@ -1741,7 +1842,8 @@ register({
       `Recall engine: ${activeEngine}`,
       `Auto-compact: ${formatCompactWindow(state)}`,
       `Vault: ${vault.isUnlocked() ? "unlocked" : "locked"} | Crons: ${cronCount}`,
-      state.runningProcess ? "Working..." : "Ready.",
+      laneBusy(peekLane(state)) ? "Working..." : "Ready.",
+      ...runningConversationLines(state),
     ].join("\n"));
   },
 });

package/core/identity.js

@@ -18,14 +18,42 @@ function defaultCanonicalForChannel(transport, channelId) {
   return channelKey(transport, channelId);
 }
 
-// The conversation (thread) key for a channel. Deliberately identical to the
-// pre-unification default canonical: a thread is keyed by its raw channel
+// The conversation key for a channel. Deliberately identical to the
+// pre-unification default canonical: a conversation is keyed by its raw channel
 // identity, never by the unified speaker canonical. This is what keeps each
 // surface's live conversation separate even when the speaker is one being.
-function conversationKeyFor(transport, channelId) {
+// A chat THREAD (Kazee "reply in thread") is a conversation of its own inside
+// the channel: `<transport>:<channelId>#thread:<rootId>`. The channel's main
+// timeline keeps the bare channel key, so nothing existing changes. The room
+// (settings, grants) stays the channel key: use roomKeyFor for that.
+const THREAD_SEP = "#thread:";
+function conversationKeyFor(transport, channelId, threadId) {
+  const base = channelKey(transport, channelId);
+  const t = String(threadId || "").trim();
+  return t ? `${base}${THREAD_SEP}${t}` : base;
+}
+
+function roomKeyFor(transport, channelId) {
   return channelKey(transport, channelId);
 }
 
+// Split a conversation key back into its parts. The channel id may itself
+// contain ':' (e.g. spaces "task:42"), so only the first ':' separates the
+// transport. Returns {transport, channelId, threadId|null, roomKey}.
+function parseConversationKey(key) {
+  const k = String(key || "");
+  const i = k.indexOf(THREAD_SEP);
+  const room = i >= 0 ? k.slice(0, i) : k;
+  const threadId = i >= 0 ? k.slice(i + THREAD_SEP.length) || null : null;
+  const c = room.indexOf(":");
+  return {
+    transport: c >= 0 ? room.slice(0, c) : room,
+    channelId: c >= 0 ? room.slice(c + 1) : "",
+    threadId,
+    roomKey: room,
+  };
+}
+
 function loadIdentities() {
   const raw = readJsonWithFallback(IDENTITIES_FILE, null);
   return {
@@ -196,6 +224,8 @@ module.exports = {
   channelKey,
   defaultCanonicalForChannel,
   conversationKeyFor,
+  roomKeyFor,
+  parseConversationKey,
   isConfiguredOwnerChannel,
   ownerCanonical,
   channelIsOwner,

package/core/io.js

@@ -2,7 +2,16 @@
 // here so that the right adapter is invoked for the in-flight message
 // without each handler having to know about transports.
 
-const { currentAdapter, currentChannelId, currentUserId } = require("./context");
+const { currentAdapter, currentChannelId, currentUserId, currentThreadId } = require("./context");
+
+// The chat thread a delivery belongs to. An explicit opts.threadId wins (null =
+// the channel's main timeline); a send aimed at ANOTHER channel never inherits
+// this turn's thread; otherwise it goes back into the thread the turn is in.
+function threadFor(opts = {}) {
+  if (opts && Object.prototype.hasOwnProperty.call(opts, "threadId")) return opts.threadId || null;
+  if (opts && opts.channelId && String(opts.channelId) !== String(currentChannelId() || "")) return null;
+  return currentThreadId();
+}
 
 // Adapters historically overloaded their send() return value: a message id
 // (Telegram numeric, Kazee ObjectId string) on success, a bare `true` when
@@ -32,7 +41,8 @@ async function send(text, opts = {}) {
     console.error("send() called outside chat context");
     return { ok: false, messageId: null, editable: false };
   }
-  return normalizeSendResult(await adapter.send(channelId, text, opts));
+  const threadId = threadFor(opts);
+  return normalizeSendResult(await adapter.send(channelId, text, threadId ? { ...opts, threadId } : opts));
 }
 
 async function editMessage(messageId, text, opts = {}) {
@@ -49,11 +59,12 @@ async function deleteMessage(messageId) {
   return adapter.delete(channelId, messageId);
 }
 
-async function sendVoice(oggPath) {
+async function sendVoice(oggPath, opts = {}) {
   const adapter = currentAdapter();
   const channelId = currentChannelId();
   if (!adapter || !channelId) return false;
-  return adapter.sendVoice(channelId, oggPath);
+  const threadId = threadFor(opts);
+  return threadId ? adapter.sendVoice(channelId, oggPath, { threadId }) : adapter.sendVoice(channelId, oggPath);
 }
 
 // Signal the end of a streamed multi-clip spoken reply. Only the voice channel
@@ -66,7 +77,7 @@ async function sendVoiceEnd() {
   return adapter.sendVoiceEnd(channelId);
 }
 
-async function sendFile(filePath, caption) {
+async function sendFile(filePath, caption, opts = {}) {
   const adapter = currentAdapter();
   const channelId = currentChannelId();
   if (!adapter || !channelId) return false;
@@ -79,14 +90,16 @@ async function sendFile(filePath, caption) {
       return false;
     }
   } catch (e) { /* fail open only on classification error; primary gate is loopback.handleSend */ }
-  return adapter.sendFile(channelId, filePath, caption);
+  const threadId = threadFor(opts);
+  return threadId ? adapter.sendFile(channelId, filePath, caption, { threadId }) : adapter.sendFile(channelId, filePath, caption);
 }
 
 async function typing(state) {
   const adapter = currentAdapter();
   const channelId = currentChannelId();
   if (!adapter || !channelId) return;
-  return adapter.typing(channelId, state);
+  const threadId = currentThreadId();
+  return threadId ? adapter.typing(channelId, state, { threadId }) : adapter.typing(channelId, state);
 }
 
 function splitMessage(text, maxLen = 4000) {
@@ -96,4 +109,4 @@ function splitMessage(text, maxLen = 4000) {
   return chunks;
 }
 
-module.exports = { send, editMessage, deleteMessage, sendVoice, sendVoiceEnd, sendFile, typing, splitMessage, normalizeSendResult };
+module.exports = { threadFor, send, editMessage, deleteMessage, sendVoice, sendVoiceEnd, sendFile, typing, splitMessage, normalizeSendResult };

package/core/jobs.js

@@ -145,6 +145,9 @@ function normalizeRunnableJob(record, options = {}) {
     adapter: context.adapter,
     adapterType: context.adapterType,
     channelId: context.channelId,
+    // The chat thread the job fires back into (null = the channel's main
+    // timeline; jobs from before threads have none).
+    threadId: nonEmpty(record.threadId),
     canonicalUserId: context.canonicalUserId,
     userId: nonEmpty(record.userId),
     provider,

package/core/loopback.js

@@ -137,6 +137,26 @@ function jobCreatorRecord(creator) {
   };
 }
 
+// The chat thread a delivery or a job belongs to. The runner hands a thread
+// turn OC_THREAD_ID, which the CLI sends as `threadId`. For a live, attested
+// run the run decides, never the payload: in its own channel the run's thread
+// (null on the main timeline, so a main turn cannot post into some other
+// thread), and in any other channel no thread (a thread id belongs to its
+// channel). A mismatching claim is logged. A caller with no live run is
+// trusted exactly as its channelId is.
+function threadForCaller(caller, channelId, claimed) {
+  const claim = claimed ? String(claimed) : null;
+  if (caller && caller.attributed) {
+    const sameChannel = String(caller.channelId || "") === String(channelId || "");
+    const attested = sameChannel && caller.threadId ? String(caller.threadId) : null;
+    if (claim && claim !== attested) {
+      console.error(`loopback: payload thread ${claim} does not match the running turn's thread ${attested || "(none)"}; using the turn's`);
+    }
+    return attested;
+  }
+  return claim;
+}
+
 // Owner gate for every owner-only kind: true only for a LIVE run the bot
 // registered as acting for the owner. The id attest (OC_SPEAKER_ATTEST) is no
 // longer enough: it is valid for the whole boot and can be lifted from another
@@ -182,18 +202,27 @@ async function handleSend(req, res, url, kind) {
     }
   } catch (e) { /* classification failure → fall through; still owner-scoped in practice */ }
 
+  // Raw-body kinds carry the run attest in headers (the body is the file).
+  const caller = callerOf({
+    originRunId: req.headers["x-oc-run-id"] || "",
+    runAttest: req.headers["x-oc-run-attest"] || "",
+  });
+  const threadId = threadForCaller(caller, channelId, url.searchParams.get("threadId"));
+
   const safeName = path.basename(fileName).replace(/[^A-Za-z0-9._-]/g, "_") || `file-${Date.now()}`;
-  const tmp = path.join(os.tmpdir(), `oc-loopback-${process.pid}-${Date.now()}-${safeName}`);
+  // Unique per request: parallel conversations may send the same file name
+  // in the same millisecond.
+  const tmp = path.join(os.tmpdir(), `oc-loopback-${process.pid}-${Date.now()}-${crypto.randomBytes(4).toString("hex")}-${safeName}`);
   await readBodyToFile(req, tmp);
 
   let ok = false;
   try {
     if (kind === "send-voice") {
-      ok = await adapter.sendVoice(channelId, tmp);
+      ok = threadId ? await adapter.sendVoice(channelId, tmp, { threadId }) : await adapter.sendVoice(channelId, tmp);
     } else if (kind === "send-photo" && typeof adapter.sendPhoto === "function") {
-      ok = await adapter.sendPhoto(channelId, tmp, caption);
+      ok = threadId ? await adapter.sendPhoto(channelId, tmp, caption, { threadId }) : await adapter.sendPhoto(channelId, tmp, caption);
     } else {
-      ok = await adapter.sendFile(channelId, tmp, caption);
+      ok = threadId ? await adapter.sendFile(channelId, tmp, caption, { threadId }) : await adapter.sendFile(channelId, tmp, caption);
     }
   } finally {
     if (kind !== "send-voice") { try { fs.unlinkSync(tmp); } catch (e) {} }
@@ -228,6 +257,7 @@ async function handleJson(req, res, url, kind) {
   // room, and all of their guards apply when it runs. An unattributed caller
   // (a process detached from any live turn) cannot schedule anything.
   let jobCreator = null;
+  let jobThreadId = null;
   if (JOB_CREATE_KINDS.has(kind)) {
     const caller = callerOf(payload);
     if (!caller.attributed) {
@@ -243,6 +273,8 @@ async function handleJson(req, res, url, kind) {
       owner: caller.owner === true,
       name: caller.name || null,
     };
+    // A job created in a thread fires back into that thread.
+    jobThreadId = threadForCaller(caller, jobCreator.channelId, payload.threadId);
   }
 
   // Owner-only kinds: notes, tasks, and the people reads. Tasks and people
@@ -290,9 +322,10 @@ async function handleJson(req, res, url, kind) {
     }
     if (!voicePath) return reply(res, 503, { error: "no TTS route available" });
 
+    const threadId = threadForCaller(callerOf(payload), channelId, payload.threadId);
     let ok = false;
     try {
-      ok = await adapter.sendVoice(channelId, voicePath);
+      ok = threadId ? await adapter.sendVoice(channelId, voicePath, { threadId }) : await adapter.sendVoice(channelId, voicePath);
     } catch (e) {
       try { fs.unlinkSync(voicePath); } catch (_) {}
       return reply(res, 500, { error: `voice send failed: ${e.message}` });
@@ -363,6 +396,7 @@ async function handleJson(req, res, url, kind) {
       adapter: jobCreator.adapter,
       adapterType: jobCreator.adapterType,
       channelId: jobCreator.channelId,
+      threadId: jobThreadId,
       canonicalUserId: jobCreator.canonicalUserId,
       userId: jobCreator.userId,
       createdBy: jobCreatorRecord(jobCreator),
@@ -394,6 +428,7 @@ async function handleJson(req, res, url, kind) {
       adapter: jobCreator.adapter,
       adapterType: jobCreator.adapterType,
       channelId: jobCreator.channelId,
+      threadId: jobThreadId,
       canonicalUserId: jobCreator.canonicalUserId,
       userId: jobCreator.userId,
       createdBy: jobCreatorRecord(jobCreator),
@@ -442,6 +477,7 @@ async function handleJson(req, res, url, kind) {
       adapter: jobCreator.adapter,
       adapterType: jobCreator.adapterType,
       channelId: jobCreator.channelId,
+      threadId: jobThreadId,
       canonicalUserId: jobCreator.canonicalUserId,
       userId: jobCreator.userId,
       createdBy: jobCreatorRecord(jobCreator),
@@ -777,7 +813,12 @@ async function handleJson(req, res, url, kind) {
         targetChannel = caller.channelId;
       }
       if (!targetAdapter || !targetChannel) return reply(res, 400, { error: "need adapter+channelId or person" });
-      const entries = readRecentTranscript(targetAdapter, targetChannel, limit);
+      // Optional thread filter: "main" = the channel's main timeline only, a
+      // thread id = that thread only; absent = the whole channel.
+      const thread = payload.thread === undefined || payload.thread === null || payload.thread === ""
+        ? undefined
+        : (String(payload.thread) === "main" ? null : String(payload.thread));
+      const entries = readRecentTranscript(targetAdapter, targetChannel, limit, { thread });
       return reply(res, 200, { ok: true, adapter: targetAdapter, channelId: targetChannel, entries });
     } catch (e) { return reply(res, 400, { error: e.message }); }
   }
@@ -830,9 +871,11 @@ async function handleJson(req, res, url, kind) {
         approverAdapter = owner.adapter;
         approverChannel = owner.channelId;
       }
+      const originThread = threadForCaller(callerOf(payload), channelId, payload.threadId);
       const rec = approvals.create({
         tool: payload.tool, verb: payload.verb || "", tier: payload.tier || "destructive",
         command: payload.command, channelId, adapter: adapterId,
+        threadId: originThread,
         canonicalUserId: payload.canonicalUserId || null,
         userId: payload.userId || null,
         provider: payload.provider || null,
@@ -860,6 +903,8 @@ async function handleJson(req, res, url, kind) {
       // <pre> needs Telegram's HTML parse mode to render; other adapters ignore it.
       const sendOpts = { keyboard };
       if (buttonAdapter.type === "telegram") sendOpts.parseMode = "HTML";
+      // The card goes into the thread the run is in, when it goes to that room.
+      if (originThread && buttonAdapter === adapter && String(buttonChannel) === String(channelId)) sendOpts.threadId = originThread;
       const { normalizeSendResult } = require("./io");
       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" }); }
@@ -875,7 +920,7 @@ async function handleJson(req, res, url, kind) {
   return reply(res, 404, { error: "not found" });
 }
 
-function readRecentTranscript(adapter, channelId, limit) {
+function readRecentTranscript(adapter, channelId, limit, { thread } = {}) {
   if (!TRANSCRIPTS_DIR) return [];
   try {
     if (!fs2.existsSync(TRANSCRIPTS_DIR)) return [];
@@ -904,11 +949,14 @@ function readRecentTranscript(adapter, channelId, limit) {
           const objChannel = String(obj.chat?.id ?? obj.channelId ?? "");
           if (objAdapter !== adapterPrefix) continue;
           if (objChannel !== channelStr) continue;
+          const objThread = obj.chat?.threadId ? String(obj.chat.threadId) : null;
+          if (thread !== undefined && objThread !== thread) continue;
           out.push({
             at: obj.at || obj.timestamp || null,
             role: obj.role || obj.author || null,
             text: typeof obj.text === "string" ? obj.text.slice(0, 600) : null,
             kind: obj.kind || null,
+            threadId: objThread,
           });
           if (out.length >= limit) break;
         } catch (e) {}

package/core/providers/claude.js

@@ -85,8 +85,12 @@ function appendSessionArgs(args, context) {
     throw providerError("INVALID_PROVIDER_CONTEXT", "resumeSessionId and continueSession are mutually exclusive");
   }
   if (context.fresh) return;
-  if (context.resumeSessionId) args.push("--resume", String(context.resumeSessionId));
-  else if (context.continueSession) args.push("--continue");
+  if (context.resumeSessionId) {
+    args.push("--resume", String(context.resumeSessionId));
+    // A thread seeded from the main conversation (OC_THREAD_SEED=fork) resumes
+    // it into a new session of its own, leaving the main session untouched.
+    if (context.forkSession === true) args.push("--fork-session");
+  } else if (context.continueSession) args.push("--continue");
   else if (context.sessionId) args.push("--resume", String(context.sessionId));
 }