clay-server 5.2.0-beta.6 → 5.2.0-beta.8

package/lib/public/modules/wireframe-workbench.js

@@ -1,3 +1,4 @@
+import { forwardStudioPresentation, registerStudioPaint } from './clay-studio-render.js';
 import { sketchBrand, sketchCredit } from './wireframe-style.js';
 import { store } from './store.js';
 import { claimRightWorkbench, registerRightWorkbench, releaseRightWorkbench } from './right-workbench.js';
@@ -80,7 +81,7 @@ function createPanel() {
 export function openWireframe(message) {
   if (!message || typeof message.source !== 'string' || new TextEncoder().encode(message.source).length > 100000) return;
   if (store.get('paneMode') && window.parent !== window) {
-    window.parent.postMessage({ type: 'clay-pane-present-wireframe', message: message, projectSlug: store.get('currentSlug'), sessionId: store.get('activeSessionId') }, window.location.origin);
+    forwardStudioPresentation(message, 'clay-pane-present-wireframe');
     return;
   }
   claimRightWorkbench('wireframe');
@@ -92,7 +93,8 @@ export function openWireframe(message) {
   el.querySelector('header strong').textContent = draft.title;
   el.querySelector('.wireframe-save-status').textContent = '';
   el.querySelector('form').hidden = true;
-  draw(draft, el).catch(function () {});
+  var painted = draw(draft, el); registerStudioPaint(Object.assign({}, message, { source: draft.source }), el.querySelector("header"), painted, el.querySelector(".wireframe-workbench-canvas"));
+  painted.catch(function () {});
 }
 function draw(draft, el) {
   var canvas = el.querySelector('.wireframe-workbench-canvas');
@@ -104,6 +106,7 @@ function draw(draft, el) {
     var image = wireframeImage(svg, draft.title);
     canvas.replaceChildren(image);
     mountWireframeViewport(canvas, image, el.querySelector('.wireframe-zoom'));
+    return image.decode ? image.decode() : undefined;
   }).catch(function (error) {
     if (store.get('wireframeDraft') !== active) throw error;
     status.textContent = error.name === 'AbortError' ? 'Rendering was interrupted. Reopen the wireframe to retry.' : error.message;

package/lib/public/style.css

@@ -90,3 +90,5 @@
 @import url("css/project-settings-modal.css");
 
 @import url("css/clay-tool-activity.css");
+
+@import url("css/contextual-clay.css");

package/lib/sdk-bridge.js

@@ -711,6 +711,10 @@ function createSDKBridge(opts) {
     // Workspace inspection and proposal posting are session-bound. Keep this
     // list exact so a future execution/mutation tool cannot inherit approval.
     var safeWorkspaceTools = {
+      "mcp__clay-workspace__read_current_context": true,
+      "mcp__clay-workspace__read_selected_context": true,
+      "mcp__clay-workspace__open_context_conversation": true,
+      "mcp__clay-workspace__read_context_navigation_receipt": true,
       "mcp__clay-workspace__read_owner_screen": true,
       "mcp__clay-workspace__inspect_owner_screen_change": true,
       "mcp__clay-workspace__control_owner_screen": true,

package/lib/server-contextual-clay-settings.js

@@ -0,0 +1,40 @@
+// Authenticated personal preferences, using the shared users/config persistence.
+function attachContextualClaySettings(ctx) {
+  function reply(res, status, data) {
+    res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+    res.end(JSON.stringify(data));
+  }
+  function identity(req) {
+    if (!ctx.isRequestAuthed(req)) return null;
+    return ctx.users.isMultiUser() ? ctx.getMultiUserFromReq(req) : { id: 'default' };
+  }
+  function handleRequest(req, res, url) {
+    if (url !== '/api/user/contextual-clay-geometry') return false;
+    var user = identity(req);
+    if (!user) { reply(res, 401, { error: 'Sign in to manage popover preferences.' }); return true; }
+    if (req.method === 'GET') {
+      try { reply(res, 200, { geometry: ctx.users.getContextualClayGeometry(user.id) }); }
+      catch (error) { reply(res, 500, { error: 'Could not read popover preference.' }); }
+      return true;
+    }
+    if (req.method !== 'PUT') { reply(res, 405, { error: 'Method not allowed.' }); return true; }
+    if (req.headers['x-clay-settings'] !== '1' || (req.headers['sec-fetch-site'] && ['same-origin', 'none'].indexOf(req.headers['sec-fetch-site']) < 0)) {
+      reply(res, 403, { error: 'Save preferences from Clay.' }); return true;
+    }
+    var body = ''; var tooLarge = false;
+    req.setEncoding('utf8');
+    req.on('data', function (chunk) { body += chunk; if (body.length > 1024 && !tooLarge) { tooLarge = true; reply(res, 413, { error: 'Request too large.' }); } });
+    req.on('end', function () {
+      if (tooLarge) return;
+      var live = identity(req);
+      if (!live || live.id !== user.id) { reply(res, 401, { error: 'Sign in again.' }); return; }
+      try {
+        var result = ctx.users.setContextualClayGeometry(live.id, JSON.parse(body));
+        reply(res, result.error ? 400 : 200, result);
+      } catch (error) { reply(res, 400, { error: 'Could not save popover preference.' }); }
+    });
+    return true;
+  }
+  return { handleRequest: handleRequest };
+}
+module.exports = { attachContextualClaySettings: attachContextualClaySettings };

package/lib/server-contextual-mate-sessions.js

@@ -0,0 +1,70 @@
+// Presentation-only session operations share Home's authoritative permissions,
+// model policy, saved-session projection and session manager. No transcript tap.
+function attachContextualMateSessions(ctx) {
+  var receipts = new Map();
+  var lifetime = 30 * 60 * 1000;
+  function stamp(mate) { return JSON.stringify([mate.id, mate.createdBy || null, mate.createdAt || null, mate.builtinKey || null]); }
+  function live(ws, userId, msg, original) {
+    if (!ctx.isActorLive(ws, userId)) throw new Error('Your account is no longer available.');
+    var found = ctx.findMateProject(userId, msg.mateId, true);
+    if (!found || found.mate.archived || found.mate.lifecycleDeletion || found.mate.createdBy && found.mate.createdBy !== userId || stamp(found.mate) !== msg.mateStamp) throw new Error('This Mate is no longer available.');
+    var status = found.ctx.getStatus();
+    if (!status || !status.isMate || status.mateId !== found.mate.id || userId && status.projectOwnerId !== userId) throw new Error('This private Mate workspace is unavailable.');
+    found.contextualManager = found.ctx.getSessionManager();
+    found.contextualRevision = JSON.stringify([status.path, status.projectOwnerId, status.mateId, stamp(found.mate)]);
+    if (original && (found.ctx !== original.ctx || found.contextualRevision !== original.contextualRevision || found.contextualManager !== original.contextualManager)) throw new Error('This Mate conversation changed.');
+    return found;
+  }
+  function reply(ws, msg, data) { ctx.sendMessage(ws, Object.assign({ type: 'contextual_mate_sessions_result', requestId: msg.requestId, mateId: msg.mateId, mateStamp: msg.mateStamp }, data)); }
+  async function perform(ws, userId, msg) {
+    try {
+      if (typeof msg.requestId !== 'string' || !/^mate-conversations-[a-z0-9-]{36}$/.test(msg.requestId)) throw new Error('Invalid conversation request.');
+      var found = live(ws, userId, msg), manager = found.ctx.getSessionManager();
+      if (!manager) throw new Error('Conversation history is unavailable.');
+      if (msg.type === 'home_mate_sessions_list') {
+        var list = ctx.listHomeSessions(found, userId);
+        reply(ws, msg, { ok: true, sessions: list.slice(0, 500), truncated: list.length > 500 }); return;
+      }
+      var session;
+      if (msg.type === 'home_mate_session_open') {
+        session = ctx.resolveHomeSession(found, userId, msg.sessionId);
+        if (!session || typeof msg.sessionOriginId !== 'string' || msg.sessionOriginId !== session.sessionOriginId) throw new Error('This conversation is no longer available.');
+      } else {
+        var now = Date.now();
+        receipts.forEach(function (entry, key) { if (now - entry.at > lifetime) receipts.delete(key); });
+        var key = JSON.stringify([userId, msg.mateId, msg.requestId]);
+        var receipt = receipts.get(key);
+        manager.sessions.forEach(function (candidate) { if (candidate.contextualCreationRequestId === msg.requestId && ctx.ownsSession(candidate, userId)) session = candidate; });
+        if (session && session.contextualCreationMateStamp !== msg.mateStamp) throw new Error('This request belongs to a replaced Mate.');
+        if (receipt && (!session || receipt.origin !== session.sessionOriginId || receipt.stamp !== msg.mateStamp)) throw new Error('The previously created conversation is no longer available.');
+        if (!session && msg.lookupOnly) throw new Error('Creation was not confirmed. Start a new chat explicitly if you still want one.');
+        if (!session) {
+          if (receipts.size >= 1024) throw new Error('Please try starting a conversation later.');
+          var resolved = await ctx.homeModels.resolveMateModel(ws, found, userId);
+          found = live(ws, userId, msg, found);
+          // Recheck after model resolution: concurrent retries select one exact session.
+          manager.sessions.forEach(function (candidate) { if (candidate.contextualCreationRequestId === msg.requestId && ctx.ownsSession(candidate, userId)) session = candidate; });
+          receipt = receipts.get(key);
+          if (receipt && (!session || receipt.origin !== session.sessionOriginId || receipt.stamp !== msg.mateStamp)) throw new Error('The previously created conversation is no longer available.');
+          if (session && session.contextualCreationMateStamp !== msg.mateStamp) throw new Error('This request belongs to a replaced Mate.');
+          if (!session) {
+            if (receipts.size >= 1024) throw new Error('Please try starting a conversation later.');
+            session = manager.createSessionRaw({ ownerId: userId, vendor: resolved.vendor, model: resolved.model, effort: resolved.effort || null });
+            session.contextualCreationRequestId = msg.requestId;
+            session.contextualCreationMateStamp = msg.mateStamp;
+            manager.saveSessionFile(session);
+          }
+        }
+        if (!ctx.ownsSession(session, userId)) throw new Error('This conversation is no longer available.');
+        receipts.set(key, { at: now, origin: session.sessionOriginId, stamp: msg.mateStamp });
+      }
+      live(ws, userId, msg, found);
+      reply(ws, msg, { ok: true, sessionId: session.localId, sessionOriginId: session.sessionOriginId });
+    } catch (error) { reply(ws, msg, { ok: false, error: error.message || 'Conversation unavailable.' }); }
+  }
+  return { handle: function (ws, userId, msg) {
+    if (msg.presentation !== 'contextual' || !/^home_mate_(sessions_list|session_open|new_session)$/.test(msg.type)) return false;
+    perform(ws, userId, msg); return true;
+  } };
+}
+module.exports = { attachContextualMateSessions: attachContextualMateSessions };

package/lib/server-home-chat.js

@@ -123,6 +123,7 @@ function attachHomeChat(deps) {
         model: sessionString(session.model, 240),
         createdAt: createdAt,
         lastActivity: lastActivity,
+        sessionOriginId: session.sessionOriginId || null,
         isProcessing: !!session.isProcessing,
         sessionRole: hierarchy[session.localId].role,
         parentSessionId: hierarchy[session.localId].parentSessionId == null ? null : sessionReference(sessionManager.sessions.get(hierarchy[session.localId].parentSessionId)),
@@ -228,6 +229,7 @@ function attachHomeChat(deps) {
   var homeDebates = attachHomeDebates({ mates: mates, findMateProject: findMateProject, ownsSession: ownsSession, sessionReference: sessionReference, sendMessage: sendMessage });
   var homeClaySessionLinks = attachHomeClaySessionLinks({
     projects: projects,
+    findMateProject: findMateProject, ownsSession: ownsSession, isActorLive: isActorLive,
     workspaceQueryService: deps.workspaceQueryService,
     projectLogsService: deps.projectLogsService,
     sendMessage: sendMessage,
@@ -300,7 +302,9 @@ function attachHomeChat(deps) {
   });
   var homeMateCreation = attachHomeMateCreation({ findMateProject: findMateProject, resolveHomeSession: resolveHomeSession, sessionReference: sessionReference, setupTap: setupTap, sendHistory: sendHistory, sendSessionList: sendSessionList, sendError: sendError, sendModelError: sendModelError, homeModels: homeModels, isActorLive: isActorLive, persistActiveSession: persistActiveSession });
   var homeMcpConsent = require('./server-home-mcp-consent').attachHomeMcpConsent({ findMateProject: findMateProject, resolveHomeSession: resolveHomeSession, messageTap: messageTap, isActorLive: isActorLive, sendError: sendError });
-  var homeClayEntry = attachHomeClayEntry({ findMateProject: findMateProject, ownsSession: ownsSession, sessionReference: sessionReference, setupSearchTap: setupSearchTap, sendHistory: sendHistory, sendSessionList: sendSessionList, sendError: sendError, sendModelError: sendModelError, homeModels: homeModels, isActorLive: isActorLive });
+  var homeClayEntry = attachHomeClayEntry({ findMateProject: findMateProject, ownsSession: ownsSession, sessionReference: sessionReference, setupSearchTap: setupSearchTap, sendHistory: sendHistory, sendSessionList: sendSessionList, sendError: sendError, sendModelError: sendModelError, sendMessage: sendMessage, homeModels: homeModels, isActorLive: isActorLive });
+
+  var contextualSessions = require('./server-contextual-mate-sessions').attachContextualMateSessions({ findMateProject: findMateProject, ownsSession: ownsSession, resolveHomeSession: resolveHomeSession, listHomeSessions: listHomeSessions, isActorLive: isActorLive, homeModels: homeModels, sendMessage: sendMessage });
 
   async function openExactSession(ws, found, userId, selected, msg) {
     await ensureSessionModel(ws, found, userId, selected, null);
@@ -448,6 +452,8 @@ function attachHomeChat(deps) {
       return false;
     }
 
+    if (contextualSessions.handle(ws, ws._clayUser ? ws._clayUser.id : null, msg)) return true;
+
     if (msg.type === "home_mate_present") {
       ws._homeChatPresented = msg.visible === true;
       return true;

package/lib/server-home-clay-entry.js

@@ -15,10 +15,12 @@ function attachHomeClayEntry(ctx) {
   }
 
   async function start(ws, userId, msg) {
+    var contextual = msg.presentation === 'contextual';
     var text = typeof msg.text === "string" ? msg.text.replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, 12000) : "";
     var requestId = typeof msg.requestId === "string" ? msg.requestId.slice(0, 240) : null;
+    if (ctx.isActorLive && !ctx.isActorLive(ws, userId)) { ctx.sendError(ws, null, 'Your account is no longer available.', requestId, null, 'actor_unavailable'); return; }
     var found = ctx.findMateProject(userId, null, true);
-    if (!found || found.mate.builtinKey !== "clay") {
+    if (!found || found.mate.builtinKey !== "clay" || found.mate.archived || ctx.isActorLive && !ctx.isActorLive(ws, userId)) {
       ctx.sendError(ws, null, "Clay is not available.", requestId, null, "mate_unavailable");
       return;
     }
@@ -27,26 +29,43 @@ function attachHomeClayEntry(ctx) {
       return;
     }
     var manager = found.ctx.getSessionManager();
+    var mateStamp = JSON.stringify([found.mate.id, found.mate.createdAt || null, found.mate.createdBy || null]);
     if (!manager || typeof manager.sendAndRecord !== "function") {
       ctx.sendError(ws, found.mate.id, "Conversation history is unavailable.", requestId, null, "session_unavailable");
       return;
     }
     var existing = findExisting(manager, userId, requestId);
     if (existing) {
+      if (contextual) {
+        if (existing.homeClayEntryMode !== 'contextual' || existing.homeClayEntryText !== text || msg.sessionOriginId && msg.sessionOriginId !== existing.sessionOriginId) { ctx.sendError(ws, found.mate.id, 'This request belongs to a different conversation.', requestId, null, 'request_mismatch'); return; }
+        ctx.sendMessage(ws, { type: 'home_clay_contextual_session', requestId: requestId, mateId: found.mate.id, sessionId: existing.localId, sessionOriginId: existing.sessionOriginId }); return;
+      }
       ctx.setupSearchTap(ws, found, existing.localId, requestId);
       ctx.sendHistory(ws, found, existing, requestId);
       ctx.sendSessionList(ws, found, userId);
       return;
     }
+    if (contextual && msg.sessionOriginId) { ctx.sendError(ws, found.mate.id, 'This new conversation is no longer available. Start a new Ask.', requestId, null, 'session_unavailable'); return; }
     var session = null;
     try {
       var resolved = await ctx.homeModels.resolveMateModel(ws, found, userId);
       if (ctx.isActorLive && !ctx.isActorLive(ws, userId)) throw new Error("Your account is no longer available.");
       var liveFound = ctx.findMateProject(userId, null, true);
-      if (!liveFound || liveFound.ctx !== found.ctx || !liveFound.mate || liveFound.mate.builtinKey !== "clay") throw new Error("Clay is no longer available.");
-      session = manager.createSession({ ownerId: userId, vendor: resolved.vendor, model: resolved.model, effort: resolved.effort || null }, null);
+      if (!liveFound || liveFound.ctx !== found.ctx || !liveFound.mate || liveFound.ctx.getSessionManager() !== manager || liveFound.mate.builtinKey !== "clay" || JSON.stringify([liveFound.mate.id, liveFound.mate.createdAt || null, liveFound.mate.createdBy || null]) !== mateStamp || liveFound.mate.archived) throw new Error("Clay is no longer available.");
+      // Another request may have completed while model resolution was awaiting.
+      if (findExisting(manager, userId, requestId)) return start(ws, userId, msg);
+      var options = { ownerId: userId, vendor: resolved.vendor, model: resolved.model, effort: resolved.effort || null };
+      // Background creation must not switch any existing pane/native writer.
+      session = contextual ? manager.createSessionRaw(options) : manager.createSession(options, null);
       session.homeClayEntryRequestId = requestId;
-      session.homeClayEntryMode = "search";
+      session.homeClayEntryMode = contextual ? 'contextual' : 'search';
+      if (contextual) {
+        session.homeClayEntryText = text;
+        session.title = text.slice(0, 80);
+        manager.saveSessionFile(session);
+        ctx.sendMessage(ws, { type: 'home_clay_contextual_session', requestId: requestId, mateId: found.mate.id, sessionId: session.localId, sessionOriginId: session.sessionOriginId });
+        return;
+      }
       manager.sendAndRecord(session, { type: "user_message", text: text });
       session.isProcessing = true;
       session.sentToolResults = {};

package/lib/server-home-clay-session-links.js

@@ -3,6 +3,18 @@
 
 function attachHomeClaySessionLinks(ctx) {
   function source(ws, msg, routedProjectSlug) {
+    if (Object.prototype.hasOwnProperty.call(msg, "contextualSource")) {
+      var hint = msg.contextualSource, userId = ws && ws._clayUser && ws._clayUser.id;
+      if (!hint || typeof hint.mateId !== "string" || !Number.isSafeInteger(hint.sessionId) || typeof hint.sessionOriginId !== "string" || typeof hint.mateStamp !== "string" || !ctx.isActorLive || !ctx.isActorLive(ws, userId)) return {};
+      var found = ctx.findMateProject && ctx.findMateProject(userId, hint.mateId, false);
+      if (!found || found.mate.archived || found.mate.lifecycleDeletion || found.mate.createdBy && found.mate.createdBy !== userId) return {};
+      var stamp = JSON.stringify([found.mate.id, found.mate.createdBy || null, found.mate.createdAt || null, found.mate.builtinKey || null]);
+      if (stamp !== hint.mateStamp || ctx.projects.get(found.slug) !== found.ctx) return {};
+      var manager = found.ctx.getSessionManager && found.ctx.getSessionManager();
+      var session = manager && manager.sessions.get(hint.sessionId);
+      if (!ctx.ownsSession(session, userId) || session.sessionOriginId !== hint.sessionOriginId) return {};
+      return { tap: { mateSlug: found.slug, mateId: found.mate.id, sessionId: hint.sessionId }, project: found.ctx, session: session };
+    }
     var tap = msg.surface === "search" ? ws._searchClayTap : ws._homeChatTap;
     if (!tap && routedProjectSlug) {
       var routedProject = ctx.projects.get(routedProjectSlug);

package/lib/server-owner-ui.js

@@ -2,6 +2,27 @@ var crypto = require('crypto');
 // Only authenticated application sockets enumerated by the server are targets.
 function attachOwnerUi(ctx) {
   var identities = new WeakMap(), capabilities = new WeakMap(), deliveries = new Map();
+  var activityOrder = 0;
+  function activity(owner, slug, sessionId, mateId, selected, source, validateSource, navigationTarget) {
+    var order = ++activityOrder;
+    var viewers = selected ? [check(owner, selected)] : sockets(owner).filter(function (viewer) {
+      var tap = viewer.ws._homeChatTap;
+      return viewer.slug === slug && viewer.sessionId === sessionId || tap && tap.mateSlug === slug && tap.sessionId === sessionId;
+    });
+    function send(message, receiptViewer) {
+      viewers.forEach(function (viewer) {
+        try {
+          if (receiptViewer && viewer.ws !== receiptViewer || !alive(viewer.ws, owner)) return;
+          if (message.phase !== 'clear' && validateSource) validateSource();
+          var live = inspect(owner, viewer.ref), tap = live.ws._homeChatTap;
+          if (message.phase !== 'clear' && (selected ? (live.slug !== viewer.slug || live.sessionId !== viewer.sessionId) && !(message.phase === 'rendered' && navigationTarget && live.slug === navigationTarget.projectSlug && live.sessionId === navigationTarget.sessionId) : !(live.slug === slug && live.sessionId === sessionId || tap && tap.mateSlug === slug && tap.sessionId === sessionId))) return;
+          live.ws.send(JSON.stringify(Object.assign({ type: 'clay_control_activity', ownerId: owner, mateId: mateId,
+            sourceSlug: slug, sourceSessionId: sessionId, order: order, recipientViewerRef: live.ref }, source, message)));
+        } catch (error) { /* Presentation cannot alter the authoritative effect. */ }
+      });
+    }
+    return { send: send, clear: function (id, sequence) { send({ version: 1, id: id, sequence: sequence, phase: 'clear' }); } };
+  }
   function alive(ws, owner) {
     return ws && ws.readyState === 1 && (!ws._clayAuthCheck || ws._clayAuthCheck()) &&
       (ctx.isMultiUser() ? !!owner && ws._clayUser && ws._clayUser.id === owner && !!ctx.findUser(owner) : !ws._clayUser);
@@ -27,7 +48,7 @@ function attachOwnerUi(ctx) {
     if (live.ws !== original.ws || live.slug !== original.slug || live.sessionId !== original.sessionId || live.supported !== original.supported) throw new Error('The selected viewer context changed. Inspect again.');
     return live;
   }
-  function deliver(owner, original, target, revalidate) {
+  function deliver(owner, original, target, revalidate, activity) {
     revalidate(); var viewer = check(owner, original);
     if (!viewer.supported) return { status: 'unsupported', delivered: false, acknowledged: false, visible: 'unknown' };
     if (deliveries.size >= 100) {
@@ -35,9 +56,15 @@ function attachOwnerUi(ctx) {
       if (deliveries.size >= 100) throw new Error('UI delivery capacity is full; wait for earlier attempts to expire.');
     }
     var id = 'navigation:' + crypto.randomUUID();
-    var record = { owner: owner, viewer: viewer, target: target, revalidate: revalidate, created: Date.now(), claimed: false,
+    var renderToken = crypto.randomUUID();
+    var record = { owner: owner, viewer: viewer, target: target, revalidate: revalidate, activity: activity, created: Date.now(), claimed: false, renderToken: renderToken, renderClosed: false,
       result: { status: 'delivered', deliveryId: id, delivered: false, acknowledged: false, visible: 'unknown' } };
     deliveries.set(id, record);
+    record.renderTimer = setTimeout(function () {
+      if (record.renderClosed) return;
+      record.renderClosed = true; record.result.renderStatus = 'unknown';
+      if (record.activity) record.activity.navigation('unknown');
+    }, ctx.renderTimeoutMs || 5000); record.renderTimer.unref();
     try {
       viewer.ws.send(JSON.stringify({ type: 'clay_navigation_offer', deliveryId: id }));
       if (!alive(viewer.ws, owner)) throw new Error('Viewer authorization or connection ended during delivery.');
@@ -48,30 +75,44 @@ function attachOwnerUi(ctx) {
   function read(owner, id) {
     var record = deliveries.get(id);
     if (!record || record.owner !== owner) throw new Error('No delivery exists for this owner.');
+    if (Date.now() - record.created > 300000) { deliveries.delete(id); throw new Error('The five-minute navigation receipt expired. Inspect the current view before any new reviewed request.'); }
     record.revalidate();
     return Object.assign({}, record.result);
   }
   function handleMessage(ws, msg) {
-    if (['clay_ui_ready', 'clay_navigation_claim', 'clay_navigation_ack'].indexOf(msg.type) < 0) return false;
+    if (['clay_ui_ready', 'clay_navigation_claim', 'clay_navigation_ack', 'clay_navigation_rendered'].indexOf(msg.type) < 0) return false;
     var owner = ctx.isMultiUser() ? ws._clayUser && ws._clayUser.id : null;
     if (!sockets(owner).some(function (item) { return item.ws === ws; })) return true;
-    if (msg.type === 'clay_ui_ready') { if (msg.version === 1) capabilities.set(ws, 1); return true; }
+    if (msg.type === 'clay_ui_ready') {
+      if (msg.version === 1) { capabilities.set(ws, 1); ws.send(JSON.stringify({ type: 'clay_control_viewer', viewerRef: identities.get(ws) })); }
+      return true;
+    }
     var record = deliveries.get(msg.deliveryId);
     if (!record || record.viewer.ws !== ws || record.owner !== owner || Date.now() - record.created > 30000) return true;
     try {
       record.revalidate();
-      if (msg.type === 'clay_navigation_claim') {
+      if (msg.type === 'clay_navigation_rendered') {
+        if (!record.renderClosed && Date.now() > record.created + (ctx.renderTimeoutMs || 5000)) { record.renderClosed = true; clearTimeout(record.renderTimer); record.result.renderStatus = 'unknown'; if (record.activity) record.activity.navigation('unknown'); }
+        if (record.renderClosed || !record.claimed || !record.result.acknowledged || record.result.clientStatus !== 'accepted' || msg.renderToken !== record.renderToken) return true;
+        var current = inspect(owner, record.viewer.ref);
+        if (current.ws !== ws || msg.sessionOriginId !== record.target.sessionOriginId || !record.target.sessionOriginId || msg.projectSlug !== record.target.projectSlug || msg.sessionId !== record.target.sessionId || msg.surface !== 'conversation' || msg.entryIndex !== record.target.entryIndex || current.slug !== record.target.projectSlug || current.sessionId !== record.target.sessionId) throw new Error('Rendered target or authenticated viewer changed.');
+        record.renderClosed = true; clearTimeout(record.renderTimer);
+        record.result.renderStatus = msg.visible === true ? 'rendered' : 'unknown'; record.result.visible = msg.visible === true ? true : 'unknown';
+        if (record.activity) record.activity.navigation(msg.visible === true ? 'rendered' : 'unknown');
+      } else if (msg.type === 'clay_navigation_claim') {
         if (record.claimed) return true;
         check(owner, record.viewer); record.claimed = true;
-        ws.send(JSON.stringify({ type: 'clay_navigation_apply', deliveryId: msg.deliveryId, target: record.target }));
+        ws.send(JSON.stringify({ type: 'clay_navigation_apply', deliveryId: msg.deliveryId, target: record.target, renderToken: record.renderToken, renderDeadline: record.created + (ctx.renderTimeoutMs || 5000) }));
       } else if (record.claimed && !record.result.acknowledged && ['accepted', 'refused', 'failed'].indexOf(msg.status) >= 0) {
         record.result.acknowledged = true;
         // Accepted only confirms invocation of the existing navigator, never rendering.
         record.result.clientStatus = msg.status;
+        if (msg.status !== 'accepted') { record.renderClosed = true; clearTimeout(record.renderTimer); }
+        if (record.activity) record.activity.navigation(msg.status === 'accepted' ? 'acknowledged' : msg.status === 'refused' ? 'cancelled' : 'failed');
       }
-    } catch (error) { record.result.status = 'failed'; record.result.error = error.message; record.result.retrySafe = false; }
+    } catch (error) { record.renderClosed = true; clearTimeout(record.renderTimer); record.result.visible = 'unknown'; record.result.status = 'failed'; record.result.error = error.message; record.result.retrySafe = false; if (record.activity) record.activity.cancel(); }
     return true;
   }
-  return { list: sockets, inspect: inspect, check: check, deliver: deliver, read: read, handleMessage: handleMessage };
+  return { list: sockets, inspect: inspect, check: check, deliver: deliver, read: read, handleMessage: handleMessage, activity: activity };
 }
 module.exports = { attachOwnerUi: attachOwnerUi };

package/lib/server-settings.js

@@ -12,11 +12,13 @@ function attachSettings(ctx) {
   var CONFIG_DIR = ctx.CONFIG_DIR;
 
   var profilePath = path.join(CONFIG_DIR, "profile.json");
+  var contextualClaySettings = require('./server-contextual-clay-settings').attachContextualClaySettings(ctx);
   var appearanceSettings = require('./server-appearance-settings').attachAppearanceSettings(ctx);
   var notificationSettings = require('./server-notification-settings').attachNotificationSettings(ctx);
   var experimentalSettings = attachExperimentalSettings(ctx);
 
   function handleRequest(req, res, fullUrl) {
+    if (contextualClaySettings.handleRequest(req, res, fullUrl)) return true;
     if (appearanceSettings.handleRequest(req, res, fullUrl)) return true;
     if (notificationSettings.handleRequest(req, res, fullUrl)) return true;
     if (experimentalSettings.handleRequest(req, res, fullUrl)) return true;

package/lib/server.js

@@ -357,6 +357,12 @@ function createServer(opts) {
 
   // --- Project registry ---
   var assignmentService = attachWorkspaceAssignmentService({
+    getPresentation: function (principal) {
+      var project = projects.get(principal.sourceProjectSlug), manager = project && project.getSessionManager(), status = project && project.getStatus();
+      var session = manager && manager.sessions.get(principal.sourceSessionId);
+      var bound = clayProductControl && session && clayProductControl.bind({ projectSlug: principal.sourceProjectSlug, projectOwnerId: status.projectOwnerId, isMate: status.isMate, mateId: status.mateId, session: session });
+      return bound && bound._presentation;
+    },
     storageDir: path.join(CONFIG_DIR, "workspace-assignments"),
     getProjects: function () { return projects; },
     isMultiUser: function () { return users.isMultiUser(); },
@@ -384,6 +390,13 @@ function createServer(opts) {
       projects.forEach(function (project, slug) { project.forEachClient(function (ws) { visit(ws, slug); }); });
     }
   });
+  var mateContextService = require('./mate-context-service').attachMateContextService({
+    getOwnerUi: function () { return ownerUiService; }, workspace: workspaceQueryService,
+    getProjects: function () { return projects; }, isMultiUser: users.isMultiUser,
+    findUser: users.findUserById, onGetProjectAccess: onGetProjectAccess,
+    canAccessProject: users.canAccessProject,
+    resolveMate: function (owner, id) { return mates.getMate(mates.buildMateCtx(users.isMultiUser() ? owner : null), id); }
+  });
   var clayProductControl = require("./clay-product-control").attachClayProductControl({
     getOwnerUi: function () { return ownerUiService; },
     getNotifications: function () { return _globalNotifications; },
@@ -1284,6 +1297,7 @@ function createServer(opts) {
         if (!require('./account-auth-socket').guardSocket(ws, req, isRequestAuthed, auth.touchSession)) return;
         ws._clayPane = wsRequest.pane;
         ws._clayPaneSession = wsRequest.paneSession;
+        ws._clayContextual = wsRequest.contextual;
         globalWs.handleConnection(ws, globalUser);
       });
       return;
@@ -1329,6 +1343,7 @@ function createServer(opts) {
       ws._clayUser = wsUser; // attach user context
       ws._clayPane = wsRequest.pane;
       ws._clayPaneSession = wsRequest.paneSession;
+      ws._clayContextual = wsRequest.contextual;
       var remoteAddr = req.socket.remoteAddress || "";
       ws._clayLocal = (remoteAddr === "127.0.0.1" || remoteAddr === "::1" || remoteAddr === "::ffff:127.0.0.1");
       // Clear cross-project unread for this project when client connects
@@ -1450,6 +1465,7 @@ function createServer(opts) {
       },
       workspaceQueryService: workspaceQueryService,
       clayProductControl: clayProductControl,
+      mateContextService: mateContextService,
       resumeLifecycleProject: function (userId) { return opts.projectLifecycle ? opts.projectLifecycle.resumeRecovered(slug, userId) : true; },
       projectLogsService: projectLogsService,
       issuesService: issuesService,
@@ -1729,6 +1745,7 @@ function createServer(opts) {
 
   function handleDmMessage(ws, msg, routedProjectSlug) {
     if (ownerUiService.handleMessage(ws, msg)) return true;
+    if (mateContextService.handleMessage(ws, msg)) return true;
     if (cursorSharingService && cursorSharingService.handleMessage(ws, msg)) return true;
     if (defaultVendorService && defaultVendorService.handleMessage(ws, msg, routedProjectSlug)) return true;
     if (contextViewService && contextViewService.handleMessage(ws, msg)) return true;

package/lib/sessions.js

@@ -211,8 +211,11 @@ function createSessionManager(opts) {
       if (session.claySchedulingReceipts) metaObj.claySchedulingReceipts = session.claySchedulingReceipts;
       if (session.mateCreationMode) metaObj.mateCreationMode = true;
       if (session.homeMateCreationPhase) metaObj.homeMateCreationPhase = session.homeMateCreationPhase;
+      if (session.contextualCreationMateStamp) metaObj.contextualCreationMateStamp = session.contextualCreationMateStamp;
+      if (session.contextualCreationRequestId) metaObj.contextualCreationRequestId = session.contextualCreationRequestId;
       if (session.homeClayEntryRequestId) metaObj.homeClayEntryRequestId = session.homeClayEntryRequestId;
       if (session.homeClayEntryMode) metaObj.homeClayEntryMode = session.homeClayEntryMode;
+      if (session.homeClayEntryText) metaObj.homeClayEntryText = session.homeClayEntryText;
       metaObj.sessionOriginId = provenanceMeta.sessionOriginId;
       if (provenanceMeta.sessionProvenance) metaObj.sessionProvenance = provenanceMeta.sessionProvenance;
       if (Array.isArray(session._workerGenerations)) metaObj.workerGenerations = session._workerGenerations;
@@ -375,8 +378,11 @@ function createSessionManager(opts) {
       if (Array.isArray(m.claySchedulingReceipts)) session.claySchedulingReceipts = m.claySchedulingReceipts;
       if (m.mateCreationMode) session.mateCreationMode = true;
       if (m.homeMateCreationPhase) session.homeMateCreationPhase = m.homeMateCreationPhase;
+      if (m.contextualCreationMateStamp) session.contextualCreationMateStamp = m.contextualCreationMateStamp;
+      if (m.contextualCreationRequestId) session.contextualCreationRequestId = m.contextualCreationRequestId;
       if (m.homeClayEntryRequestId) session.homeClayEntryRequestId = m.homeClayEntryRequestId;
       if (m.homeClayEntryMode) session.homeClayEntryMode = m.homeClayEntryMode;
+      if (m.homeClayEntryText) session.homeClayEntryText = m.homeClayEntryText;
       if (m.ownerId) session.ownerId = m.ownerId;
       session.sessionOriginId = m.sessionOriginId || null;
       session._provenanceMigrationNeeded = sessionProvenance.restore(m, session);
@@ -561,6 +567,7 @@ function createSessionManager(opts) {
     var unreadMap = wsUnread || singleUserUnread;
     return {
       id: s.localId,
+      sessionOriginId: s.sessionOriginId || null,
       cliSessionId: s.cliSessionId || null,
       createdAt: s.createdAt || 0,
       title: s.title || "New Session",
@@ -771,8 +778,8 @@ function createSessionManager(opts) {
   }
 
   // History entries include tool activity and streamed output, so opening a
-  // conversation needs a wider window than each incremental scroll-up page.
-  var INITIAL_HISTORY_SIZE = 500;
+  // conversation starts with a 300-entry target, aligned to a complete user turn.
+  var INITIAL_HISTORY_SIZE = 300;
   var HISTORY_PAGE_SIZE = 100;
 
   function findTurnBoundary(history, targetIndex) {
@@ -826,7 +833,7 @@ function createSessionManager(opts) {
       }
     }
 
-    _send({ type: "history_done", lastUsage: lastUsage, lastModelUsage: lastModelUsage, lastCost: lastCost, lastStreamInputTokens: lastStreamInputTokens, context: lastContext, contextUsage: require("./yoke/usage").context(session.lastContextUsage, session.vendor || "claude") });
+    _send({ type: "history_done", controlHistoryRevision: require("./clay-control-target-projection").digest(session.history || []), sessionId: session.localId, sessionOriginId: session.sessionOriginId || null, lastUsage: lastUsage, lastModelUsage: lastModelUsage, lastCost: lastCost, lastStreamInputTokens: lastStreamInputTokens, context: lastContext, contextUsage: require("./yoke/usage").context(session.lastContextUsage, session.vendor || "claude") });
     for (var vi = 0; vi < sessionViewedListeners.length; vi++) {
       try { sessionViewedListeners[vi](session, targetWs, _send); } catch (e) {}
     }

package/lib/terminal-manager.js

@@ -83,7 +83,7 @@ function createTerminalManager(opts) {
       }
 
       // Broadcast to subscribers
-      var msg = JSON.stringify({ type: "term_output", id: id, data: data });
+      var msg = JSON.stringify(Object.assign({ type: "term_output", id: id, data: data }, controlProjection(id)));
       for (var ws of session.subscribers) {
         if (ws.readyState === 1) ws.send(msg);
       }
@@ -108,7 +108,7 @@ function createTerminalManager(opts) {
       }
 
       // Broadcast updated list
-      send({ type: "term_list", terminals: list() });
+      send({ type: "term_list", terminals: list(true) });
 
       // Caller-supplied hook: e.g. TUI session manager uses this to delete
       // its session record once `claude` exits, so stale entries don't pile
@@ -181,10 +181,11 @@ function createTerminalManager(opts) {
         session.cols = cols;
         session.rows = rows;
         // Notify other subscribers about the resize so their xterm stays in sync
-        var msg = JSON.stringify({ type: "term_resized", id: id, cols: cols, rows: rows });
+        var msg = JSON.stringify(Object.assign({ type: "term_resized", id: id, cols: cols, rows: rows }, controlProjection(id)));
         for (var ws of session.subscribers) {
           if (ws.readyState === 1 && ws !== sourceWs) ws.send(msg);
         }
+        if (sourceWs && sourceWs.readyState === 1) sourceWs.send(JSON.stringify(Object.assign({ type: "term_control_projection", id: id }, controlProjection(id))));
       } catch (e) {}
     }
   }
@@ -244,15 +245,24 @@ function createTerminalManager(opts) {
     session.title = String(title).substring(0, 50);
   }
 
-  function list() {
+  function inspect(id) {
+      var terminal = terminals.get(id);
+      return terminal ? { id: id, identity: terminal.identity, ownerId: terminal.ownerId, osIdentity: terminal.osIdentity, title: terminal.title, kind: terminal.kind, exited: terminal.exited, cols: terminal.cols, rows: terminal.rows, totalBytesWritten: terminal.totalBytesWritten } : null;
+  }
+
+  function controlProjection(id) { var item = inspect(id); return item ? { controlIdentity: item.identity, controlRevision: require('./clay-control-target-projection').digest(item) } : {}; }
+
+  function list(control) {
     var result = [];
     for (var session of terminals.values()) {
-      result.push({
+      var entry = {
         id: session.id,
         title: session.title,
         kind: session.kind,
         exited: session.exited,
-      });
+      };
+      if (control) { entry.controlIdentity = session.identity; entry.controlRevision = require('./clay-control-target-projection').digest(inspect(session.id)); }
+      result.push(entry);
     }
     return result;
   }
@@ -333,10 +343,7 @@ function createTerminalManager(opts) {
     resize: resize,
     close: close,
     closeAndWait: closeAndWait,
-    inspect: function (id) {
-      var terminal = terminals.get(id);
-      return terminal ? { id: id, identity: terminal.identity, ownerId: terminal.ownerId, osIdentity: terminal.osIdentity, title: terminal.title, kind: terminal.kind, exited: terminal.exited, cols: terminal.cols, rows: terminal.rows, totalBytesWritten: terminal.totalBytesWritten } : null;
-    },
+    inspect: inspect,
     resizeExact: function (id, cols, rows, identity, revalidate) {
       revalidate();
       var terminal = terminals.get(id);
@@ -345,7 +352,7 @@ function createTerminalManager(opts) {
       revalidate();
       if (terminals.get(id) !== terminal) throw new Error('Terminal was replaced during resize.');
       terminal.cols = cols; terminal.rows = rows;
-      var message = JSON.stringify({ type: 'term_resized', id: id, cols: cols, rows: rows });
+      var message = JSON.stringify(Object.assign({ type: 'term_resized', id: id, cols: cols, rows: rows }, controlProjection(id)));
       terminal.subscribers.forEach(function (ws) { if (ws.readyState === 1) ws.send(message); });
       return true;
     },

package/lib/users-contextual-clay-preferences.js

@@ -0,0 +1,31 @@
+// Personal geometry is never a canonical product-control operation.
+function validGeometry(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  var keys = Object.keys(value);
+  if (keys.length !== 4 || keys.some(function (key) { return ['left', 'top', 'width', 'height'].indexOf(key) < 0; })) return false;
+  return keys.every(function (key) { return typeof value[key] === 'number' && Number.isFinite(value[key]); }) &&
+    value.left >= 0 && value.left <= 16384 && value.top >= 0 && value.top <= 16384 &&
+    value.width >= 340 && value.width <= 2560 && value.height >= 360 && value.height <= 2160;
+}
+function attachContextualClayPreferences(deps) {
+  function get(userId) {
+    var user = deps.loadUsers().users.find(function (entry) { return entry.id === userId; });
+    var saved = user && user.contextualClayGeometry;
+    if (!user && userId === 'default') saved = require('./config').loadConfig().contextualClayGeometry;
+    return validGeometry(saved) ? Object.assign({}, saved) : null;
+  }
+  function set(userId, geometry) {
+    if (!validGeometry(geometry)) return { error: 'Invalid popover geometry.' };
+    var value = Object.assign({}, geometry);
+    var data = deps.loadUsers();
+    var user = data.users.find(function (entry) { return entry.id === userId; });
+    if (user) { user.contextualClayGeometry = value; deps.saveUsers(data); }
+    else if (userId === 'default') {
+      var config = require('./config');
+      config.saveConfig(Object.assign({}, config.loadConfig(), { contextualClayGeometry: value }));
+    } else return { error: 'Account no longer available.' };
+    return { geometry: value };
+  }
+  return { getContextualClayGeometry: get, setContextualClayGeometry: set };
+}
+module.exports = { attachContextualClayPreferences: attachContextualClayPreferences, validGeometry: validGeometry };