clay-server 4.0.0-beta.13 → 4.0.0-beta.15

package/lib/public/modules/home-tool-frame.js

@@ -0,0 +1,165 @@
+// home-tool-frame.js - host side of the sandboxed rich Display frame.
+//
+// A rich element is additive Display: it renders in an iframe on a separate
+// anonymous origin with sandbox="allow-scripts" and a frame CSP that allows
+// no network at all. Its only channel is postMessage, and the only thing it
+// can request is an act, which the host routes through the exact callback the
+// floor buttons use. The floor never depends on the frame: if the frame fails
+// to load or go ready, the host falls back to the floor automatically.
+
+import { getWs } from './ws-ref.js';
+
+var READY_TIMEOUT_MS = 6000;
+var MAX_ACTION_LENGTH = 64;
+
+var frames = Object.create(null);
+
+// One listener for every frame. Messages are matched to a frame by the
+// window they came from, never by origin text: a sandboxed frame without
+// allow-same-origin reports the opaque origin "null", so identity comes from
+// the contentWindow reference the host itself created.
+var listenerAttached = false;
+
+function ensureListener() {
+  if (listenerAttached) return;
+  listenerAttached = true;
+  window.addEventListener("message", function (event) {
+    var toolIds = Object.keys(frames);
+    var entry = null;
+    for (var i = 0; i < toolIds.length; i++) {
+      var candidate = frames[toolIds[i]];
+      if (candidate.iframe && candidate.iframe.contentWindow === event.source) {
+        entry = candidate;
+        break;
+      }
+    }
+    if (!entry) return;
+    var data = event.data;
+    if (!data || data.clayCapsuleFrame !== 1 || typeof data.type !== "string") return;
+    if (data.type === "ready") {
+      markReady(entry);
+      return;
+    }
+    if (data.type === "act") {
+      // The frame asks; the host decides. Bounded validation here, then the
+      // same pipeline as a floor button click. Nothing else is accepted.
+      if (typeof data.actionId !== "string" || !data.actionId || data.actionId.length > MAX_ACTION_LENGTH) return;
+      if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(data.actionId)) return;
+      var args = data.args && typeof data.args === "object" && !Array.isArray(data.args) ? data.args : {};
+      entry.onAct(data.actionId, args);
+    }
+  });
+}
+
+function markReady(entry) {
+  if (entry.ready) return;
+  entry.ready = true;
+  if (entry.readyTimer) {
+    clearTimeout(entry.readyTimer);
+    entry.readyTimer = null;
+  }
+  for (var i = 0; i < entry.queue.length; i++) {
+    postToFrame(entry, entry.queue[i]);
+  }
+  entry.queue.length = 0;
+  if (entry.onReady) entry.onReady();
+}
+
+function postToFrame(entry, payload) {
+  if (!entry.iframe || !entry.iframe.contentWindow) return;
+  // targetOrigin must be "*": a sandboxed frame without allow-same-origin has
+  // an opaque origin no origin string can name. Delivery is still exact,
+  // because the message goes to the one contentWindow this host created, and
+  // the payload is only the projection already chosen for this element.
+  entry.iframe.contentWindow.postMessage(payload, "*");
+}
+
+function failFrame(toolId, message) {
+  var entry = frames[toolId];
+  if (!entry) return;
+  disposeFrame(toolId);
+  if (entry.onUnavailable) entry.onUnavailable(message);
+}
+
+// Mounts the rich element for one Capsule. The frame URL is requested over
+// the authenticated WebSocket and answered by handleToolFrameUrlState below.
+export function mountRichDisplay(options) {
+  var toolId = options.toolId;
+  disposeFrame(toolId);
+  ensureListener();
+  frames[toolId] = {
+    toolId: toolId,
+    container: options.container,
+    onAct: options.onAct,
+    onReady: options.onReady || null,
+    onUnavailable: options.onUnavailable || null,
+    iframe: null,
+    ready: false,
+    queue: [],
+    readyTimer: null,
+  };
+  var ws = getWs();
+  if (!ws || ws.readyState !== 1) {
+    failFrame(toolId, "The connection to the server is not available.");
+    return;
+  }
+  ws.send(JSON.stringify({ type: "tool_frame_url", toolId: toolId }));
+}
+
+export function handleToolFrameUrlState(msg) {
+  if (!msg || !msg.toolId) return;
+  var entry = frames[msg.toolId];
+  if (!entry || entry.iframe) return;
+  if (msg.ok === false || !msg.frame || !msg.frame.port) {
+    failFrame(msg.toolId, msg.error || "The rich Display is unavailable.");
+    return;
+  }
+  var scheme = msg.frame.secure ? "https" : "http";
+  var url = scheme + "://" + window.location.hostname + ":" + msg.frame.port + msg.frame.path;
+  var iframe = document.createElement("iframe");
+  iframe.className = "home-tool-frame";
+  // allow-scripts only. No allow-same-origin, so the frame's origin is opaque
+  // and nothing of the host origin (DOM, cookies, storage) is reachable.
+  iframe.setAttribute("sandbox", "allow-scripts");
+  iframe.setAttribute("title", "Capsule rich display");
+  iframe.src = url;
+  entry.iframe = iframe;
+  entry.container.appendChild(iframe);
+  entry.readyTimer = setTimeout(function () {
+    failFrame(msg.toolId, "The rich Display did not become ready.");
+  }, READY_TIMEOUT_MS);
+}
+
+export function pushFrameState(toolId, state) {
+  var entry = frames[toolId];
+  if (!entry) return;
+  var payload = { clayCapsuleFrame: 1, type: "state", state: state || {} };
+  if (!entry.ready) {
+    entry.queue.push(payload);
+    return;
+  }
+  postToFrame(entry, payload);
+}
+
+export function pushFrameEvent(toolId, event) {
+  var entry = frames[toolId];
+  if (!entry || !event) return;
+  var payload = { clayCapsuleFrame: 1, type: "event", event: event };
+  if (!entry.ready) {
+    entry.queue.push(payload);
+    return;
+  }
+  postToFrame(entry, payload);
+}
+
+export function hasFrame(toolId) {
+  return !!frames[toolId];
+}
+
+export function disposeFrame(toolId) {
+  var entry = frames[toolId];
+  if (!entry) return;
+  if (entry.readyTimer) clearTimeout(entry.readyTimer);
+  if (entry.iframe && entry.iframe.parentNode) entry.iframe.parentNode.removeChild(entry.iframe);
+  delete frames[toolId];
+}

package/lib/public/modules/home-tools.js

@@ -9,6 +9,7 @@ import { showToast } from './utils.js';
 import { createToolLlmStatus, initialToolLlmAlias } from './tool-llm-status.js';
 import { isToolModelAlias, shouldInjectToolLlmStatus } from './tool-ui-tree.js';
 import { mountCapsuleHostControls, disposeCapsuleHostControls, handleToolSourceState as applyToolSourceState, handleToolMateAccessState as applyToolMateAccessState } from './home-capsule-source.js';
+import { mountRichDisplay, pushFrameState, pushFrameEvent, disposeFrame } from './home-tool-frame.js';
 
 var definitions = Object.create(null);
 var runtimes = Object.create(null);
@@ -16,6 +17,8 @@ var registeredIds = Object.create(null);
 var errorSurfaces = Object.create(null);
 var displays = Object.create(null);
 var llmStatuses = Object.create(null);
+var serverStates = Object.create(null);
+var serverEventSeqs = Object.create(null);
 
 export function requestTools() {
   var ws = getWs();
@@ -29,6 +32,7 @@ function stopRuntime(toolId) {
   if (runtimes[toolId]) runtimes[toolId].stop();
   if (llmStatuses[toolId]) llmStatuses[toolId].dispose();
   if (displays[toolId]) disposeToolUi(displays[toolId]);
+  disposeFrame(toolId);
   delete runtimes[toolId];
   delete errorSurfaces[toolId];
   delete displays[toolId];
@@ -52,6 +56,125 @@ function renderRuntimeState(toolId, state) {
   }, display);
 }
 
+// Server-runtime Capsules hold their Logic on the server, so the human's click
+// travels the same act pipeline a Mate's clay_tool_act call travels. The
+// browser only renders the state Logic hands back.
+function sendServerControl(toolId, request) {
+  var ws = getWs();
+  if (!ws || ws.readyState !== 1) {
+    showRuntimeError(toolId, "The connection to the server is not available.");
+    return;
+  }
+  ws.send(JSON.stringify({
+    type: "tool_server_control",
+    toolId: toolId,
+    kind: request.kind,
+    actionId: request.actionId || null,
+    args: request.args || {},
+  }));
+}
+
+function renderServerState(toolId, state) {
+  var definition = definitions[toolId];
+  var display = displays[toolId];
+  if (!definition || !display) return;
+  renderToolUi(toolId, definition.uiTree, state || {}, function (actionName, args) {
+    sendServerControl(toolId, { kind: "act", actionId: actionName, args: args });
+  }, display);
+}
+
+// Applies a server-runtime Capsule state if it is not older than what is
+// already rendered. States carry the Logic's monotonic eventSeq, so a slow
+// snapshot response can never roll the Display back behind a pushed event.
+function applyServerState(toolId, state) {
+  state = state || {};
+  // A successful read or event clears any stale refusal either way.
+  var surface = errorSurfaces[toolId];
+  if (surface) surface.classList.add("hidden");
+  var seq = Number.isInteger(state.eventSeq) ? state.eventSeq : null;
+  var lastSeq = serverEventSeqs[toolId];
+  if (seq !== null && lastSeq !== undefined && seq <= lastSeq) return false;
+  if (seq !== null) serverEventSeqs[toolId] = seq;
+  serverStates[toolId] = state;
+  renderServerState(toolId, state);
+  return true;
+}
+
+// Brief host-side attribution when the other seat acts: the Display flashes
+// and the dock icon pulses, so a watching human can tell the change was the
+// Mate operating the same interface. The meaning itself stays in state; this
+// is only the host pointing at it.
+function flashRemoteAct(toolId) {
+  pulseDockTool(toolId);
+  var display = displays[toolId];
+  if (!display) return;
+  display.classList.remove("capsule-remote-act");
+  void display.offsetWidth;
+  display.classList.add("capsule-remote-act");
+  setTimeout(function () { display.classList.remove("capsule-remote-act"); }, 900);
+}
+
+export function handleToolServerState(msg) {
+  if (!msg || !msg.toolId) return;
+  if (msg.ok === false) {
+    showRuntimeError(msg.toolId, msg.error || "The Capsule action failed.");
+    return;
+  }
+  if (applyServerState(msg.toolId, msg.state)) pushFrameState(msg.toolId, msg.state || {});
+}
+
+// The push half of the shared-interface effect: Logic changed, no matter whose
+// act changed it, so every open Display for this user re-renders. Events are
+// applied one by one in seq order, so consecutive acts replay as steps rather
+// than collapsing into a final state. The rich frame receives the full causal
+// event so it can animate and attribute the transition.
+export function handleToolServerEvent(msg) {
+  if (!msg || !msg.toolId || !msg.event || !msg.event.next) return;
+  if (!applyServerState(msg.toolId, msg.event.next)) return;
+  pushFrameEvent(msg.toolId, msg.event);
+  if (msg.event.actor && msg.event.actor !== "user") flashRemoteAct(msg.toolId);
+}
+
+// Mounts the additive rich element above the floor. The floor is rendered
+// first and stays a click away behind the toggle, and any frame failure
+// (no URL, load error, never ready) falls back to the floor silently: the
+// rich element may enrich the Capsule, never gate it.
+function mountServerFrame(toolId, root, floorEl) {
+  var frameWrap = document.createElement("div");
+  frameWrap.className = "home-tool-frame-wrap hidden";
+  frameWrap.dataset.capsuleRuntimeSurface = "true";
+  var toggle = document.createElement("button");
+  toggle.type = "button";
+  toggle.className = "home-tool-frame-toggle hidden";
+  toggle.dataset.capsuleRuntimeSurface = "true";
+  var showingFrame = false;
+  function setView(rich) {
+    showingFrame = rich;
+    frameWrap.classList.toggle("hidden", !rich);
+    floorEl.classList.toggle("hidden", rich);
+    toggle.textContent = rich ? "Standard controls" : "Rich view";
+  }
+  toggle.addEventListener("click", function () { setView(!showingFrame); });
+  root.appendChild(frameWrap);
+  root.appendChild(toggle);
+  mountRichDisplay({
+    toolId: toolId,
+    container: frameWrap,
+    onAct: function (actionId, args) {
+      sendServerControl(toolId, { kind: "act", actionId: actionId, args: args });
+    },
+    onReady: function () {
+      toggle.classList.remove("hidden");
+      setView(true);
+    },
+    onUnavailable: function () {
+      toggle.classList.add("hidden");
+      setView(false);
+    },
+  });
+  pushFrameState(toolId, serverStates[toolId] || {});
+}
+
 function ensureRuntime(toolId) {
   if (runtimes[toolId]) return runtimes[toolId];
   var definition = definitions[toolId];
@@ -102,8 +225,11 @@ function mountTool(toolId, contentEl, chromeEl) {
     var serverDisplay = document.createElement("div");
     serverDisplay.className = "home-tool-display";
     serverDisplay.dataset.capsuleRuntimeSurface = "true";
+    if (definition.hasRichDisplay) mountServerFrame(toolId, root, serverDisplay);
     root.appendChild(serverDisplay);
-    renderToolUi(toolId, definition.uiTree, {}, function () {}, serverDisplay);
+    displays[toolId] = serverDisplay;
+    renderServerState(toolId, serverStates[toolId] || {});
+    sendServerControl(toolId, { kind: "snapshot" });
     return;
   }
   var runtime = ensureRuntime(toolId);
@@ -189,6 +315,8 @@ export function handleToolMateAccessState(msg) {
 export function handleToolRemoved(msg) {
   stopRuntime(msg.toolId);
   delete definitions[msg.toolId];
+  delete serverStates[msg.toolId];
+  delete serverEventSeqs[msg.toolId];
   delete registeredIds[msg.toolId];
   unregisterDockTool(msg.toolId);
   syncStore();

package/lib/public/modules/session-hierarchy.js

@@ -0,0 +1,54 @@
+// Pure projection shared by desktop, mobile and Home session lists.
+
+export function buildSessionHierarchy(sessions) {
+  var source = Array.isArray(sessions) ? sessions : [];
+  var byId = new Map();
+  var workersByParent = new Map();
+  var roots = [];
+  var orphans = [];
+  for (var i = 0; i < source.length; i++) byId.set(nodeId(source[i]), source[i]);
+  for (var j = 0; j < source.length; j++) {
+    var session = source[j];
+    if (session.sessionRole !== "worker") {
+      roots.push({ driver: session, workers: [] });
+      continue;
+    }
+    var parent = session.parentAvailable ? byId.get(parentNodeId(session)) : null;
+    if (!parent || parent.sessionRole === "worker") {
+      orphans.push(session);
+      continue;
+    }
+    if (!workersByParent.has(nodeId(parent))) workersByParent.set(nodeId(parent), []);
+    workersByParent.get(nodeId(parent)).push(session);
+  }
+  for (var k = 0; k < roots.length; k++) {
+    roots[k].workers = workersByParent.get(nodeId(roots[k].driver)) || [];
+    roots[k].workers.sort(compareWorkers);
+    roots[k].lastActivity = latestActivity(roots[k]);
+  }
+  orphans.sort(compareWorkers);
+  return { roots: roots, orphans: orphans };
+}
+
+function nodeId(session) {
+  return session && session.hierarchyId != null ? session.hierarchyId : session.id;
+}
+
+function parentNodeId(session) {
+  return session && session.parentHierarchyId != null ? session.parentHierarchyId : session.parentSessionId;
+}
+
+function compareWorkers(a, b) {
+  var ag = typeof a.workerGeneration === "number" ? a.workerGeneration : 0;
+  var bg = typeof b.workerGeneration === "number" ? b.workerGeneration : 0;
+  if (ag !== bg) return bg - ag;
+  return (b.lastActivity || 0) - (a.lastActivity || 0);
+}
+
+export function latestActivity(root) {
+  var latest = root.driver.lastActivity || 0;
+  for (var i = 0; i < root.workers.length; i++) {
+    if ((root.workers[i].lastActivity || 0) > latest) latest = root.workers[i].lastActivity || 0;
+  }
+  return latest;
+}

package/lib/public/modules/sidebar-mobile.js

@@ -37,6 +37,11 @@ import { openHomeChat } from './home-mate-chat.js';
 import { openTerminal } from './terminal.js';
 import { requestKnowledgeList } from './mate-knowledge.js';
 import { loadRootDirectory } from './filebrowser.js';
+import {
+  prepareSidebarHierarchy,
+  renderMobileDriverHierarchy,
+  renderMobileOrphanHierarchy
+} from './sidebar-session-hierarchy.js';
 
 // --- Mobile state ---
 var mobileChatSheetOpen = false;
@@ -374,9 +379,11 @@ function renderSheetSessions(listEl) {
 }
 
 // Helper: create a mobile session item element
-function createMobileSessionItem(s) {
+function createMobileSessionItem(s, options) {
+  var itemOptions = options || {};
   var el = document.createElement("button");
   el.className = "mobile-session-item" + (s.active ? " active" : "");
+  if (itemOptions.worker) el.classList.add("mobile-worker-item");
 
   // Vendor badge (legacy sessions without a vendor are Claude)
   var mVendor = s.vendor || "claude";
@@ -398,6 +405,13 @@ function createMobileSessionItem(s) {
   titleSpan.appendChild(document.createTextNode(s.title || "New Session"));
   el.appendChild(titleSpan);
 
+  if (itemOptions.worker) {
+    var generation = document.createElement("span");
+    generation.className = "mobile-worker-generation" + (itemOptions.current ? " current" : "");
+    generation.textContent = itemOptions.current ? "Current" : (s.workerGeneration ? "Gen " + s.workerGeneration : "Worker");
+    el.appendChild(generation);
+  }
+
   // Unread badge (right side)
   if (s.unread > 0 && !s.active) {
     var badge = document.createElement("span");
@@ -720,10 +734,13 @@ function renderMobileSessionsInto(container) {
 
   // Partition: loop sessions vs normal sessions (same logic as desktop renderSessionList)
   var sessions = getCachedSessions();
+  var hierarchy = prepareSidebarHierarchy(sessions);
+  var hierarchyByDriver = hierarchy.byDriver;
   var loopGroups = {};
   var normalSessions = [];
   for (var i = 0; i < sessions.length; i++) {
     var s = sessions[i];
+    if (s.sessionRole === "worker") continue;
     if (s.loop && s.loop.loopId && s.loop.role === "crafting" && s.loop.source !== "ralph" && s.loop.source !== "debate") {
       continue;
     } else if (s.loop && s.loop.loopId) {
@@ -740,7 +757,14 @@ function renderMobileSessionsInto(container) {
   // Build virtual items
   var items = [];
   for (var j = 0; j < normalSessions.length; j++) {
-    items.push({ type: "session", data: normalSessions[j], lastActivity: normalSessions[j].lastActivity || 0 });
+    var driverRoot = hierarchyByDriver.get(normalSessions[j].id);
+    if (driverRoot) items.push({ type: "driver-hierarchy", data: driverRoot.driver, root: driverRoot, lastActivity: driverRoot.lastActivity });
+    else items.push({ type: "session", data: normalSessions[j], lastActivity: normalSessions[j].lastActivity || 0 });
+  }
+  if (hierarchy.orphans.length) {
+    var orphanActivity = 0;
+    for (var oi = 0; oi < hierarchy.orphans.length; oi++) orphanActivity = Math.max(orphanActivity, hierarchy.orphans[oi].lastActivity || 0);
+    items.push({ type: "orphan-workers", workers: hierarchy.orphans, lastActivity: orphanActivity });
   }
   var groupKeys = Object.keys(loopGroups);
   for (var k = 0; k < groupKeys.length; k++) {
@@ -757,8 +781,8 @@ function renderMobileSessionsInto(container) {
 
   // Sort by lastActivity descending
   items.sort(function (a, b) {
-    var aBookmarked = !!(a.type === "loop" ? false : a.data && a.data.bookmarked);
-    var bBookmarked = !!(b.type === "loop" ? false : b.data && b.data.bookmarked);
+    var aBookmarked = !!(a.type === "loop" || a.type === "orphan-workers" ? false : a.data && a.data.bookmarked);
+    var bBookmarked = !!(b.type === "loop" || b.type === "orphan-workers" ? false : b.data && b.data.bookmarked);
     if (aBookmarked !== bBookmarked) return aBookmarked ? -1 : 1;
     return (b.lastActivity || 0) - (a.lastActivity || 0);
   });
@@ -767,7 +791,7 @@ function renderMobileSessionsInto(container) {
   var regularItems = [];
   for (var n = 0; n < items.length; n++) {
     var item = items[n];
-    if (item.type === "session" && item.data && item.data.bookmarked) {
+    if ((item.type === "session" || item.type === "driver-hierarchy") && item.data && item.data.bookmarked) {
       bookmarkedItems.push(item);
     } else {
       regularItems.push(item);
@@ -781,7 +805,8 @@ function renderMobileSessionsInto(container) {
     container.appendChild(bookmarkedHeader);
 
     for (var bi = 0; bi < bookmarkedItems.length; bi++) {
-      container.appendChild(createMobileSessionItem(bookmarkedItems[bi].data));
+      if (bookmarkedItems[bi].type === "driver-hierarchy") container.appendChild(renderMobileDriverHierarchy(bookmarkedItems[bi].root, createMobileSessionItem, refreshMobileChatSheet));
+      else container.appendChild(createMobileSessionItem(bookmarkedItems[bi].data));
     }
   }
 
@@ -800,6 +825,10 @@ function renderMobileSessionsInto(container) {
     }
     if (item.type === "loop") {
       container.appendChild(createMobileLoopGroup(item.loopId, item.children, item.groupKey));
+    } else if (item.type === "driver-hierarchy") {
+      container.appendChild(renderMobileDriverHierarchy(item.root, createMobileSessionItem, refreshMobileChatSheet));
+    } else if (item.type === "orphan-workers") {
+      container.appendChild(renderMobileOrphanHierarchy(item.workers, createMobileSessionItem, refreshMobileChatSheet));
     } else {
       container.appendChild(createMobileSessionItem(item.data));
     }