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

package/lib/public/modules/contextual-mate-sessions.js

@@ -0,0 +1,134 @@
+// Saved conversations are independent of which compact renderers are mounted.
+import { store } from './store.js';
+import { getWs } from './ws-ref.js';
+import { contextualMate, contextualMateStamp, contextualFrame } from './contextual-mate-identity.js';
+import { selectContextualConversation } from './contextual-clay.js';
+import { pauseContextualSearchForSelection } from './contextual-search.js';
+import { iconHtml, refreshIcons } from './icons.js';
+import { showToast } from './utils.js';
+
+function selection() { var value = store.get('contextualClay') || {}; return JSON.stringify([value.mateId, value.sessionId, value.startingAsk]); }
+function host() { return document.getElementById('contextual-clay'); }
+function requestState(kind) { return store.get(kind === 'list' ? 'contextualConversationHistory' : 'contextualConversationRequest'); }
+function save(kind, value) { var update = {}; update[kind === 'list' ? 'contextualConversationHistory' : 'contextualConversationRequest'] = value; store.set(update); }
+function valid(request) { var mate = request && contextualMate(request.mateId); return request && request.ownerId === store.get('myUserId') && mate && contextualMateStamp(mate) === request.stamp; }
+function guardDraft() {
+  var frame = contextualFrame();
+  try {
+    if (frame && frame.conversation) frame.conversation.checkDraft();
+    return true;
+  } catch (error) { showToast(error.message, 'warn'); return false; }
+}
+function send(kind, item, lookup) {
+  var mate = contextualMate((store.get('contextualClay') || {}).mateId), socket = getWs();
+  if (!mate) return;
+  var old = requestState(kind);
+  if (kind !== 'list' && old && old.status === 'loading') { showToast('Wait for the current conversation request to finish.', 'warn'); return; }
+  if (kind !== 'list' && !guardDraft()) return;
+  var request = lookup ? Object.assign({}, old) : { requestId: 'mate-conversations-' + crypto.randomUUID(), mateId: mate.id, stamp: contextualMateStamp(mate), ownerId: store.get('myUserId'), selection: selection(), kind: kind, item: item };
+  if (!valid(request)) return;
+  request.status = 'loading'; request.error = null; request.socket = socket;
+  save(kind, request);
+  if (!store.get('connected') || !socket || socket.readyState !== 1) { save(kind, Object.assign({}, request, { status: 'error', error: 'Reconnect to load or start a conversation.' })); return; }
+  var payload = { type: kind === 'list' ? 'home_mate_sessions_list' : kind === 'new' ? 'home_mate_new_session' : 'home_mate_session_open', presentation: 'contextual', mateId: request.mateId, mateStamp: request.stamp, requestId: request.requestId };
+  if (item) { payload.sessionId = item.id; payload.sessionOriginId = item.sessionOriginId; }
+  if (lookup && kind === 'new') payload.lookupOnly = true;
+  try { socket.send(JSON.stringify(payload)); }
+  catch (error) { save(kind, Object.assign({}, request, { status: 'error', error: 'The request is unconfirmed. Check again after reconnecting.' })); }
+  setTimeout(function () {
+    var current = requestState(kind);
+    if (current && current.requestId === request.requestId && current.status === 'loading') save(kind, Object.assign({}, current, { status: 'error', error: kind === 'new' ? 'Creation is unconfirmed. Check the same request or browse history.' : 'Conversation history did not respond. Try again.' }));
+  }, 15000);
+}
+function age(timestamp) {
+  if (!timestamp) return '';
+  var date = new Date(timestamp), today = new Date();
+  return date.toDateString() === today.toDateString() ? 'Today' : date.toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+}
+function render() {
+  var surface = host(); if (!surface) return;
+  var mateId = (store.get('contextualClay') || {}).mateId;
+  var request = requestState('action'), history = requestState('list');
+  var busy = request && request.mateId === mateId && request.status === 'loading';
+  surface.querySelector('[data-mate-new]').disabled = !!busy;
+  surface.querySelector('[data-mate-new]').setAttribute('aria-busy', String(!!busy));
+  var notice = surface.querySelector('[data-conversation-notice]');
+  notice.hidden = !request || request.mateId !== mateId || request.status === 'done';
+  if (!notice.hidden) {
+    notice.querySelector('span').textContent = request.error || (request.kind === 'new' ? 'Starting a new chat…' : 'Opening conversation…');
+    notice.querySelector('button').hidden = request.status !== 'error';
+    notice.querySelector('button').textContent = request.kind === 'new' ? 'Check request' : 'Try again';
+  }
+  var list = surface.querySelector('[data-mate-session-list]');
+  if (!surface.querySelector('[data-mate-history]').open) return;
+  var key = JSON.stringify([history && history.requestId, history && history.status, history && history.error, mateId, (store.get('contextualClay') || {}).sessionId, !!busy]);
+  if (list.dataset.renderKey === key) return;
+  list.dataset.renderKey = key;
+  list.replaceChildren();
+  if (!history || history.mateId !== mateId || history.status !== 'done') {
+    var status = document.createElement('p'); status.setAttribute('role', 'status');
+    status.textContent = history && history.mateId === mateId && history.error || 'Loading conversations…'; list.appendChild(status);
+    if (history && history.status === 'error') { var retry = document.createElement('button'); retry.type = 'button'; retry.textContent = 'Try again'; retry.onclick = function () { send('list'); }; list.appendChild(retry); }
+    return;
+  }
+  if (!history.sessions.length) { var empty = document.createElement('p'); empty.textContent = 'No saved conversations yet.'; list.appendChild(empty); }
+  history.sessions.forEach(function (item) {
+    var button = document.createElement('button'); button.type = 'button'; button.dataset.sessionId = String(item.localId);
+    button.setAttribute('aria-current', String(String((store.get('contextualClay') || {}).sessionId) === String(item.localId)));
+    var title = document.createElement('span'); title.textContent = item.title || 'New conversation';
+    var detail = document.createElement('small'); detail.textContent = item.isProcessing ? 'Working' : age(item.lastActivity || item.createdAt);
+    button.append(title, detail); button.title = title.textContent; button.disabled = !!busy;
+    button.onclick = function () { send('open', item); };
+    list.appendChild(button);
+  });
+  if (history.truncated) { var limit = document.createElement('p'); limit.textContent = 'Showing the 500 most recent conversations.'; list.appendChild(limit); }
+}
+export function attachContextualConversations(surface) {
+  var actions = surface.querySelector('.contextual-clay-actions');
+  var tools = document.createElement('div'); tools.className = 'contextual-conversation-tools';
+  tools.innerHTML = '<button type="button" data-mate-new aria-label="New chat" title="New chat">' + iconHtml('square-pen') + '<span>New chat</span></button><details data-mate-history><summary role="button" aria-label="Conversation history" aria-haspopup="dialog" aria-expanded="false" aria-controls="contextual-conversation-history" title="Conversation history">' + iconHtml('history') + '</summary><div id="contextual-conversation-history" role="dialog" aria-label="Conversation history"><span class="contextual-history-label">Conversations</span><div data-mate-session-list></div></div></details>';
+  actions.prepend(tools);
+  var notice = document.createElement('div'); notice.dataset.conversationNotice = ''; notice.hidden = true;
+  notice.innerHTML = '<span role="status"></span><button type="button">Check request</button>';
+  surface.insertBefore(notice, surface.querySelector('.contextual-clay-body'));
+  tools.querySelector('[data-mate-new]').onclick = function () { send('new'); };
+  tools.querySelector('details').addEventListener('toggle', function () { this.querySelector('summary').setAttribute('aria-expanded', String(this.open)); if (this.open) send('list'); });
+  surface.addEventListener('pointerdown', function (event) { var menu = tools.querySelector('details'); if (menu.open && !menu.contains(event.target)) menu.open = false; });
+
+  notice.querySelector('button').onclick = function () { var value = requestState('action'); if (value) send(value.kind, value.item, true); };
+  tools.addEventListener('keydown', function (event) {
+    if (event.key === 'Tab') {
+      var menu = tools.querySelector('details'), items = Array.from(tools.querySelectorAll('[data-mate-session-list] button:not(:disabled)'));
+      if (menu.open && (event.shiftKey && event.target === menu.querySelector('summary') || !event.shiftKey && event.target === items[items.length - 1])) queueMicrotask(function () { menu.open = false; });
+      return;
+    }
+    if (!/^Arrow(Down|Up)$/.test(event.key)) return;
+    var buttons = Array.from(tools.querySelectorAll('[data-mate-session-list] button:not(:disabled)'));
+    if (!buttons.length) return;
+    var index = buttons.indexOf(document.activeElement);
+    buttons[index < 0 ? (event.key === 'ArrowDown' ? 0 : buttons.length - 1) : (index + (event.key === 'ArrowDown' ? 1 : buttons.length - 1)) % buttons.length].focus(); event.preventDefault();
+  });
+  refreshIcons(); render();
+}
+export function handleContextualConversations(msg) {
+  if (msg.type !== 'contextual_mate_sessions_result') return false;
+  var kind = requestState('list') && requestState('list').requestId === msg.requestId ? 'list' : 'action';
+  var request = requestState(kind);
+  if (!request || request.status !== 'loading' || request.requestId !== msg.requestId || request.socket !== getWs() || !valid(request) || msg.mateId !== request.mateId || msg.mateStamp !== request.stamp) return true;
+  if (!msg.ok) { save(kind, Object.assign({}, request, { status: 'error', error: msg.error || 'Conversation unavailable.' })); return true; }
+  if (kind === 'list') { save(kind, Object.assign({}, request, { status: 'done', sessions: msg.sessions || [], truncated: msg.truncated })); return true; }
+  if (!Number.isSafeInteger(msg.sessionId) || msg.sessionId <= 0 || typeof msg.sessionOriginId !== 'string') return true;
+  if (request.selection !== selection() || (store.get('contextualClay') || {}).mode !== 'popover') { save(kind, Object.assign({}, request, { status: 'error', error: 'Your selection changed. The conversation remains in history.' })); return true; }
+  if (!guardDraft()) { save(kind, Object.assign({}, request, { status: 'error', error: 'Finish uploading or recording, then check this conversation again.' })); return true; }
+  pauseContextualSearchForSelection();
+  if (!selectContextualConversation(contextualMate(request.mateId), msg.sessionId, msg.sessionOriginId)) { save(kind, Object.assign({}, request, { status: 'error', error: 'This conversation could not be opened. Your draft is retained.' })); return true; }
+  surfaceClose(true); save(kind, Object.assign({}, request, { status: 'done' })); return true;
+}
+function surfaceClose(restoreFocus) { var surface = host(); if (surface) { var menu = surface.querySelector('[data-mate-history]'); var focused = menu.contains(document.activeElement); menu.open = false; if (focused || restoreFocus) menu.querySelector('summary').focus({ preventScroll: true }); } }
+store.subscribe(function (value, previous) {
+  if (value.paneMode) return;
+  if (value.myUserId !== previous.myUserId) { store.set({ contextualConversationHistory: null, contextualConversationRequest: null }); return; }
+  if ((value.contextualClay || {}).mateId !== (previous.contextualClay || {}).mateId) surfaceClose();
+  if (previous.connected && !value.connected) ['list', 'action'].forEach(function (kind) { var request = requestState(kind); if (request && request.status === 'loading') save(kind, Object.assign({}, request, { status: 'error', error: 'Disconnected. Check again when connected; your conversation is retained.' })); });
+  render();
+});

package/lib/public/modules/contextual-search.js

@@ -0,0 +1,137 @@
+import { store } from './store.js';
+import { getWs } from './ws-ref.js';
+import { activateContextualMate } from './project-mate-navigation.js';
+import { contextualMate, contextualMateStamp, contextualFrame } from './contextual-mate-identity.js';
+import { showContextualAsk, enterComposer } from './contextual-clay.js';
+import { showToast } from './utils.js';
+
+function current() { return store.get('contextualSearchAsk'); }
+function view() { return JSON.stringify([store.get('myUserId'), store.get('currentSlug'), store.get('activeSessionId'), store.get('homeShellVisible'), store.get('homeSubSurface'), store.get('dmMode'), store.get('rightWorkbenchOwner'), store.get('rightWorkbenchRevision')]); }
+function patch(change) { store.set({ contextualSearchAsk: Object.assign({}, current(), change) }); }
+function live(request) {
+  var mate = contextualMate(request.mateId);
+  return request.ownerId === store.get('myUserId') && mate && mate.builtinKey === 'clay' && contextualMateStamp(mate) === request.stamp;
+}
+function sendCreation() {
+  var request = current(), ws = getWs();
+  if (!request || !live(request)) { patch({ status: 'error', error: 'Clay is unavailable. Your question is retained.' }); return; }
+  if (!store.get('connected') || !ws || ws.readyState !== 1) { patch({ status: 'error', error: 'Reconnect, then retry. Your question is retained.' }); return; }
+  patch({ status: 'creating', socket: ws, view: view(), error: null });
+  try { ws.send(JSON.stringify({ type: 'home_clay_ask', presentation: 'contextual', requestId: request.requestId, text: request.text, sessionOriginId: request.sessionOriginId || null })); }
+  catch (error) { patch({ status: 'error', error: 'Creation is unconfirmed. Retry checks the same request.' }); }
+  setTimeout(function () { if (current() && current().requestId === request.requestId && current().status === 'creating') patch({ status: 'error', error: 'Conversation creation is unconfirmed. Retry checks the same request.' }); }, 15000);
+}
+export function pauseContextualSearchForSelection() {
+  if (current() && /^(creating|opening)$/.test(current().status)) stop();
+}
+function stop(execution) {
+  var request = current(), frame = request && request.sessionId && contextualFrame(request.mateId, request.sessionId);
+  if (frame && frame.conversation) { if (execution === true) frame.conversation.stopAsk(); else frame.conversation.pauseAsk(); }
+  patch({ status: 'stopped', error: request && request.clientMessageId ? 'Automatic delivery is paused. Inspect the conversation to confirm whether work stopped.' : 'Stopped before submission. Your question is retained; it will not be submitted automatically.' });
+}
+function resume() {
+  var request = current();
+  if (!request || !live(request)) return;
+  if (request.clientMessageId) { showToast('Inspect this conversation before retrying an uncertain message.', 'warn'); return; }
+  showContextualAsk(contextualMate(request.mateId), request.requestId, request.sessionId);
+  sendCreation();
+}
+function submit() {
+  var request = current();
+  if (!request || request.status !== 'opening') return;
+  if (!live(request) || request.view !== view()) { patch({ status: 'error', error: 'The view changed. Retry explicitly from the current view.' }); return; }
+  var frame = contextualFrame(request.mateId, request.sessionId);
+  if (!frame || frame.hidden || !frame.conversation || !frame.conversation.identity().ready) return;
+  var identity = frame.conversation.identity();
+  if (identity.ownerId !== request.ownerId || identity.sessionId !== request.sessionId || identity.sessionOriginId !== request.sessionOriginId || identity.mateId !== request.mateId) { patch({ status: 'error', error: 'The exact conversation identity changed. Nothing was submitted.' }); return; }
+  patch({ status: 'sending' });
+  var receipt = frame.conversation.submitAsk({ requestId: request.requestId, text: request.text, ownerId: request.ownerId, sessionId: request.sessionId, sessionOriginId: request.sessionOriginId });
+  if (!receipt || !receipt.clientMessageId) { patch({ status: 'error', error: 'Submission is unconfirmed. Inspect the retained question before retrying.' }); return; }
+  patch({ status: 'sent', clientMessageId: receipt.clientMessageId });
+}
+function render() {
+  var host = document.getElementById('contextual-clay');
+  if (!host) return;
+  var status = host.querySelector('[data-contextual-ask-status]');
+  if (!status) {
+    status = document.createElement('section'); status.dataset.contextualAskStatus = ''; status.setAttribute('role', 'region'); status.setAttribute('aria-label', 'Pending question');
+    status.innerHTML = '<div class="contextual-pending-question"><span>Pending question</span><blockquote data-ask-question></blockquote></div><div class="contextual-pending-progress"><p role="status" aria-live="polite" aria-atomic="true"></p><div><button type="button" data-ask-retry>Retry</button><button type="button" data-ask-stop>Stop</button><button type="button" data-ask-inspect>Open conversation</button></div></div>';
+    host.querySelector('.contextual-clay-body').appendChild(status);
+    status.querySelector('[data-ask-inspect]').addEventListener('click', function () { var request = current(); if (request && live(request)) activateContextualMate(request.mateId); });
+    status.querySelector('[data-ask-retry]').addEventListener('click', resume);
+    status.querySelector('[data-ask-stop]').addEventListener('click', function () { stop(true); });
+    host.addEventListener('contextual-clay-ready', submit);
+    host.addEventListener('contextual-clay-availability', function () {
+      var request = current(), frame = request && contextualFrame(request.mateId, request.sessionId);
+      if (request && request.status === 'opening' && frame && frame.conversation && frame.conversation.identity().available === false) patch({ status: 'error', error: 'This new conversation is unavailable. Your question is retained.' });
+    });
+    host.addEventListener('contextual-context-submitted', function (event) {
+      var request = current(), frame = request && contextualFrame(request.mateId, request.sessionId);
+      if (request && frame && frame.contentWindow === event.detail.source && request.clientMessageId && request.clientMessageId === event.detail.message.clientMessageId) patch({ status: 'acknowledged', acknowledged: true });
+    });
+    host.addEventListener('contextual-ask-stopped', function (event) { var request = current(), frame = request && contextualFrame(request.mateId, request.sessionId); if (frame && frame.contentWindow === event.detail.source) stop(); });
+  }
+  var focused = document.activeElement, ownedFocus = status.contains(focused);
+  var request = current(), selected = store.get('contextualClay') || {};
+  status.hidden = !request || selected.mateId !== request.mateId || request.acknowledged || request.status === 'acknowledged' || selected.sessionId && selected.sessionId !== request.sessionId;
+  if (request) {
+    status.querySelector('[data-ask-question]').textContent = request.text;
+    status.querySelector('p').textContent = request.error || (request.status === 'creating' ? 'Starting a new conversation. Your question is waiting.' : request.status === 'opening' ? 'Preparing this conversation. Nothing submitted yet.' : 'Waiting for confirmation. Delivery is not confirmed yet.');
+    status.querySelector('[data-ask-inspect]').hidden = !request.clientMessageId;
+    status.querySelector('[data-ask-retry]').hidden = request.status !== 'error' && request.status !== 'stopped' || !!request.clientMessageId;
+    status.querySelector('[data-ask-stop]').hidden = request.status === 'stopped';
+  }
+  host.dataset.askPending = String(!status.hidden);
+  var selectedFrame = contextualFrame();
+  host.querySelector('[data-clay-loading]').hidden = !status.hidden || !!(selectedFrame && selectedFrame.conversation && selectedFrame.conversation.identity().ready);
+  host.querySelectorAll('iframe').forEach(function (frame) { frame.inert = !status.hidden && frame.dataset.mateId === request.mateId && String(frame.dataset.sessionId) === String(request.sessionId); });
+  if (status.hidden) {
+    enterComposer();
+    if (ownedFocus && selectedFrame && selectedFrame.conversation && selectedFrame.conversation.identity().ready) selectedFrame.contentDocument.getElementById('input').focus({ preventScroll: true });
+  } else if (ownedFocus && focused.hidden) {
+    var nextControl = status.querySelector('[data-ask-retry]:not([hidden]), [data-ask-inspect]:not([hidden]), [data-ask-stop]:not([hidden])');
+    if (nextControl) nextControl.focus({ preventScroll: true });
+  }
+
+}
+
+export function startContextualSearch(text) {
+  text = typeof text === 'string' ? text.trim().slice(0, 12000) : '';
+  var mate = (store.get('cachedMatesList') || []).find(function (item) { return item.builtinKey === 'clay' && contextualMate(item.id); });
+  if (!text || !mate) { showToast('Clay is unavailable. Your question remains in Search.', 'warn'); return false; }
+  var request = current();
+  if (request && /^(creating|opening|sending|sent)$/.test(request.status)) { showToast('Clay is still starting the previous question. This question remains in Search.', 'warn'); return false; }
+  var requestId = 'contextual-search-' + crypto.randomUUID();
+  if (!showContextualAsk(mate, requestId, null)) return false;
+  store.set({ contextualSearchAsk: { requestId: requestId, text: text, mateId: mate.id, ownerId: store.get('myUserId'), stamp: contextualMateStamp(mate), status: 'creating', view: view() } });
+  render(); sendCreation(); return true;
+}
+export function retryContextualSearch() {
+  var request = current();
+  if (!request || !live(request) || request.clientMessageId || !/^(error|stopped)$/.test(request.status)) return false;
+  resume(); return true;
+}
+export function handleContextualSearchMessage(msg) {
+  var request = current();
+  if (!request || request.requestId !== msg.requestId) return false;
+  if (msg.type === 'home_mate_error') { patch({ status: 'error', error: msg.text || 'The conversation could not be started. Your question is retained.' }); return true; }
+  if (msg.type !== 'home_clay_contextual_session') return false;
+  if (request.status !== 'creating' || request.socket !== getWs() || !live(request) || request.mateId !== msg.mateId || !Number.isSafeInteger(msg.sessionId) || msg.sessionId <= 0 || typeof msg.sessionOriginId !== 'string' || request.sessionOriginId && request.sessionOriginId !== msg.sessionOriginId) return true;
+  if (request.view !== view()) { patch({ sessionId: msg.sessionId, sessionOriginId: msg.sessionOriginId, status: 'error', error: 'The view changed. Retry explicitly from the current view.' }); return true; }
+  patch({ sessionId: msg.sessionId, sessionOriginId: msg.sessionOriginId, status: 'opening' });
+  showContextualAsk(contextualMate(request.mateId), request.requestId, msg.sessionId);
+  var frame = contextualFrame(request.mateId, msg.sessionId);
+  if (frame) frame.dataset.contextualTitle = request.text.slice(0, 80);
+  setTimeout(function () { if (current() && current().requestId === request.requestId && current().status === 'opening') patch({ status: 'error', error: 'The conversation is not ready. Retry checks this same conversation.' }); }, 15000);
+  submit(); return true;
+}
+store.subscribe(function (value, previous) {
+  if (current() && current().ownerId !== value.myUserId) { store.set({ contextualSearchAsk: null }); return; }
+  if (current() && !live(current()) && /^(creating|opening)$/.test(current().status)) patch({ status: 'error', error: 'Clay is no longer available. Your question is retained.' });
+  if (current() && previous.connected && !value.connected && /^(creating|opening)$/.test(current().status)) patch({ status: 'error', error: 'Disconnected. Retry checks the same new conversation; your question is retained.' });
+  render();
+});
+document.addEventListener('click', function (event) {
+  var request = current();
+  if (request && store.get('currentSlug') === 'mate-' + request.mateId && store.get('activeSessionId') === request.sessionId && event.target.closest('#generation-stop, #autonomous-run-stop, #send-btn.stop')) stop();
+}, true);

package/lib/public/modules/contextual-session-citations.js

@@ -0,0 +1,58 @@
+// Human citation clicks leave the pinned pane intact and use the parent viewer's
+// existing authenticated reference resolver, never a project label as a target.
+import { store } from './store.js';
+import { getWs } from './ws-ref.js';
+import { contextualFrame, contextualMate, contextualMateStamp } from './contextual-mate-identity.js';
+import { parseClaySessionReference } from './clay-log-links.js';
+import { requestClayRecordLink } from './command-palette.js';
+
+function capture() {
+  var frame = contextualFrame(), state = store.get('contextualClay') || {}, mate = contextualMate(state.mateId);
+  var identity = frame && frame.conversation && frame.conversation.identity();
+  if (!mate || state.mode !== 'popover' || !frame || frame.hidden || frame.inert || !identity || !identity.ready || frame.conversation.source !== frame.contentWindow || identity.ownerId !== store.get('myUserId') || identity.mateId !== mate.id || frame.dataset.identityStamp !== contextualMateStamp(mate)) return null;
+  var surface = document.getElementById('contextual-clay');
+  return { mateId: mate.id, stamp: contextualMateStamp(mate), sessionId: identity.sessionId, originId: identity.sessionOriginId, ownerId: identity.ownerId, view: surface.dataset.screenReference, socket: getWs() };
+}
+export function validContextualCitation(context) {
+  var live = capture();
+  return !!(context && live && live.socket === context.socket && live.mateId === context.mateId && live.stamp === context.stamp && live.sessionId === context.sessionId && live.originId === context.originId && live.ownerId === context.ownerId && live.view === context.view);
+}
+export function contextualCitationLink(context, requestId) {
+  var frames = Array.from(document.querySelectorAll('#contextual-clay iframe'));
+  for (var frame of frames) {
+    var mate = contextualMate(frame.dataset.mateId), identity = frame.conversation && frame.conversation.identity();
+    if (!mate || !identity || identity.ownerId !== store.get('myUserId') || frame.dataset.identityStamp !== contextualMateStamp(mate)) continue;
+    if (context && (identity.mateId !== context.mateId || identity.sessionId !== context.sessionId || identity.sessionOriginId !== context.originId || context.ownerId !== identity.ownerId)) continue;
+    var link = Array.from(frame.contentDocument.querySelectorAll('.clayos-session-link')).find(function (item) { return item.dataset.sessionRequest === requestId; });
+    if (link) return link;
+  }
+  return null;
+}
+export function attachContextualSessionCitations(surface) {
+  surface.resolveSessionCitation = function (source, link) {
+    var context = capture(), frame = contextualFrame();
+    if (!context || !frame || frame.contentWindow !== source || !link || link.ownerDocument !== frame.contentDocument || !link.closest('.msg-assistant') || !parseClaySessionReference(link.dataset.sessionRef || '')) return false;
+    context.ref = link.dataset.sessionRef;
+    return requestClayRecordLink(link, context);
+  };
+}
+export function forwardContextualSessionCitation(link) {
+  if (!store.get('paneMode') || new URLSearchParams(location.search).get('contextual') !== '1') return false;
+  try {
+    var surface = window.parent.document.getElementById('contextual-clay');
+    if (surface && surface.resolveSessionCitation && surface.resolveSessionCitation(window, link)) return true;
+  } catch (error) { /* A changed authentication document cannot receive clicks. */ }
+  if (link.classList.contains('is-error')) return true;
+  link.classList.add('is-error'); link.title = 'This conversation or view changed. Reopen it before navigating.';
+  return true;
+}
+// Project transport replacement may discard an old reply before the palette
+// sees it. Retire that pending UI receipt at the context change itself.
+store.subscribe(function (value) {
+  var pending = value.sessionNavigationRequestContext;
+  if (value.paneMode || !pending || !pending.citation) return;
+  if (pending.projectSlug === value.currentSlug && pending.sessionId === value.activeSessionId && validContextualCitation(pending.citation)) return;
+  var link = contextualCitationLink(pending.citation, value.sessionNavigationRequestId);
+  if (link) { link.classList.remove('is-loading'); link.classList.add('is-error'); link.title = 'The view changed. Click again from the current conversation.'; delete link.dataset.sessionRequest; }
+  store.set({ sessionNavigationRequestId: null, sessionNavigationRequestContext: null });
+});

package/lib/public/modules/filebrowser.js

@@ -1,3 +1,5 @@
+import { presentedDocument, refreshPresentedDocument, closePresentedDocument } from './clay-studio-document.js';
+import { registerStudioPaint } from './clay-studio-render.js';
 import { iconHtml, refreshIcons } from './icons.js';
 import { escapeHtml, copyToClipboard } from './utils.js';
 import { renderMarkdown, highlightCodeBlocks, renderMermaidBlocks, exportMarkdownAsPdf } from './markdown.js';
@@ -192,6 +194,9 @@ export function initFileBrowser(_ctx) {
 
   document.getElementById("file-viewer-download").addEventListener("click", function () {
     if (!currentFilePath) return;
+    if ((store.get("studioDocumentView") || {}).descriptor && store.get("studioDocumentView").descriptor.path === currentFilePath) {
+      var link = document.createElement('a'); link.href = URL.createObjectURL(new Blob([currentContent || ''], { type: 'text/markdown;charset=utf-8' })); link.download = currentFilePath.split('/').pop(); link.click(); setTimeout(function () { URL.revokeObjectURL(link.href); }, 1000); return;
+    }
     downloadProjectFile(currentFilePath);
   });
 
@@ -459,12 +464,14 @@ function handleTreeKeyDown(e) {
 
 // --- File watch helpers ---
 function sendWatch(filePath) {
+  if ((store.get("studioDocumentView") || {}).descriptor && store.get("studioDocumentView").descriptor.path === filePath) return;
   if (ctx.ws && ctx.connected) {
     ctx.ws.send(JSON.stringify({ type: "fs_watch", path: filePath }));
   }
 }
 
 function sendUnwatch() {
+  if (store.get("studioDocumentView")) { closePresentedDocument(); return; }
   if (ctx.ws && ctx.connected) {
     ctx.ws.send(JSON.stringify({ type: "fs_unwatch" }));
   }
@@ -532,6 +539,7 @@ export function resetFileBrowser() {
   treeData = {};
   currentContent = null;
   currentFilePath = null;
+  store.set({ clayControlFileView: null });
   isRendered = false;
   currentIsMarkdown = false;
   currentIsSvg = false;
@@ -568,6 +576,7 @@ export function openFile(filePath, opts) {
   if (!state.connected) return false;
   if (opts && opts.projectSlug && opts.projectSlug !== state.currentSlug) return false;
   if (opts && opts.sessionId && String(opts.sessionId) !== String(state.activeSessionId)) return false;
+  closePresentedDocument();
   var workbenchRevision = claimRightWorkbench("file-viewer");
   if (followedFileChanged(filePath) || (opts && opts.diff && isFollowingMarkdown(filePath))) {
     cancelMarkdownFollow();
@@ -635,6 +644,7 @@ export function presentMarkdownEdit(msg) {
     content: typeof msg.content === "string" ? msg.content : "",
     size: msg.size || 0,
   });
+  registerStudioPaint(msg, document.querySelector("#file-viewer .file-viewer-header"), null, document.getElementById("file-viewer-body"));
 }
 
 function followedFileChanged(filePath) {
@@ -723,6 +733,7 @@ function requestDirectory(dirPath) {
 }
 
 function requestFileContent(filePath) {
+  if (refreshPresentedDocument(filePath)) return;
   var requestId = "file-read-" + Date.now() + "-" + Math.random().toString(36).slice(2);
   var state = store.snap();
   store.set({ fileReadRequest: { requestId: requestId, path: filePath, projectSlug: state.currentSlug || null, sessionId: state.activeSessionId != null ? String(state.activeSessionId) : null, accountId: state.myUserId || null, workbenchRevision: store.get('rightWorkbenchRevision') || 0 } });
@@ -1148,6 +1159,7 @@ function renderEntries(container, entries, depth) {
 // --- File viewer ---
 
 function showFileContent(msg, expectedRevision) {
+  var priorTarget = document.querySelector("#file-viewer .file-viewer-header"); if (priorTarget) delete priorTarget.dataset.controlSurface;
   if (!updateFileViewerTab(msg.path, { content: msg.content })) return;
   if (expectedRevision != null && !isRightWorkbenchCurrent("file-viewer", expectedRevision)) return;
   var pathEl = document.getElementById("file-viewer-path");
@@ -1170,6 +1182,8 @@ function showFileContent(msg, expectedRevision) {
   pendingRefresh = false;
   currentContent = null;
   currentFilePath = msg.path;
+  var sourceView = store.get('studioDocumentView'), sourceDescriptor = sourceView && sourceView.descriptor.path === msg.path ? sourceView.descriptor : null;
+  store.set({ clayControlFileView: { path: msg.path, revision: msg.controlRevision || null, projectSlug: sourceDescriptor ? sourceDescriptor.sourceSlug : store.get('currentSlug'), runtimeId: sourceDescriptor ? sourceDescriptor.runtimeId : store.get('controlRuntimeId') } });
   currentIsMarkdown = false;
   currentIsSvg = false;
   store.set({ fileViewerIsPlantUml: false, fileViewerIsHtml: false });
@@ -1279,6 +1293,8 @@ function showFileContent(msg, expectedRevision) {
     store.set({ pendingFileNavigation: null });
   }
 
+  var sourceView = presentedDocument(msg.path);
+  if (sourceView) Array.from(bodyEl.querySelectorAll('.clay-file-link')).forEach(function (link) { link.dataset.fileProjectSlug = sourceView.descriptor.sourceSlug; link.dataset.fileSessionId = String(sourceView.descriptor.sourceSessionId); });
   // Request edit history for this file (skip on auto-refresh)
   if (!keepRenderState) {
     historyVisible = false;
@@ -1361,7 +1377,9 @@ function pathsReferToSameFile(left, right) {
   return a === b || a.endsWith("/" + b) || b.endsWith("/" + a);
 }
 
-export function handleFileChanged(msg) {
+export function handleFileChanged(msg, presentedSource) {
+  var source = store.get('studioDocumentView');
+  if (source && source.descriptor.path === msg.path && (!presentedSource || presentedDocument(msg.path) !== presentedSource)) return;
   if (!msg.path || !pathsReferToSameFile(msg.path, currentFilePath)) return;
   if (ctx.fileViewerEl.classList.contains("hidden")) return;
   if (historyVisible || inlineDiffActive) return;
@@ -1602,6 +1620,7 @@ function formatSize(bytes) {
 // --- File edit history ---
 
 function requestFileHistory(filePath) {
+  if ((store.get("studioDocumentView") || {}).descriptor && store.get("studioDocumentView").descriptor.path === filePath) return;
   if (ctx.ws && ctx.connected) {
     ctx.ws.send(JSON.stringify({ type: "fs_file_history", path: filePath }));
   }

package/lib/public/modules/generation-stop.js

@@ -2,6 +2,13 @@ import { store } from './store.js';
 import { getWs } from './ws-ref.js';
 import { isDriverOperatedView } from './worker-pane-lock.js';
 
+export function stopGeneration() {
+  var ws = getWs();
+  if (!store.get('processing') || !store.get('connected') || !ws || ws.readyState !== 1) return false;
+  ws.send(JSON.stringify({ type: 'stop' }));
+  return true;
+}
+
 // Fallback Stop control for when Send cannot double as Stop: a draft sitting
 // in the composer (Send stays Send so the draft can still go out), or a
 // locked configured Worker pane (Send and the rest of the composer are
@@ -31,11 +38,7 @@ export function initGenerationStop() {
     button.title = store.get('connected') ? 'Stop generating' : 'Reconnect to stop generating';
     place();
   }
-  button.addEventListener('click', function () {
-    var ws = getWs();
-    if (!store.get('processing') || !store.get('connected') || !ws || ws.readyState !== 1) return;
-    ws.send(JSON.stringify({ type: 'stop' }));
-  });
+  button.addEventListener('click', stopGeneration);
   store.subscribe(function (state, previous) {
     if (state.processing !== previous.processing || state.connected !== previous.connected
       || state.splitGroups !== previous.splitGroups || state.activeSessionId !== previous.activeSessionId

package/lib/public/modules/git-panel.js

@@ -103,7 +103,8 @@ function renderFileRow(file, staged) {
   var actionTitle = staged ? "Unstage file — keep its changes" : "Stage file for commit";
   var actionIcon = staged ? "minus" : "plus";
   var actionsOpen = expandedFileActionsPath === file.path;
-  return '<div class="git-file-row' + (actionsOpen ? ' active' : '') + '">' +
+  var control = currentStatus && currentStatus.controlView, view = control && control.files.find(function (item) { return item.path === file.path; });
+  return '<div data-control-git-path="' + escapeHtml(file.path) + '" data-control-revision="' + escapeHtml(view && view.revision || '') + '" data-control-runtime="' + escapeHtml(control && control.runtimeId || '') + '" class="git-file-row' + (actionsOpen ? ' active' : '') + '">' +
     '<span class="git-file-status' + statusClass + '">' + escapeHtml(fileStatusLabel(file, staged)) + '</span>' +
     '<div class="git-file-main" data-git-file-item="' + pathKey + '" tabindex="0" aria-label="File actions for ' + escapeHtml(parts.name) + '" aria-expanded="' + (actionsOpen ? 'true' : 'false') + '">' +
       '<div class="git-file-name">' + escapeHtml(parts.name) + '</div>' +
@@ -282,6 +283,7 @@ export function refreshGitStatus() {
   return requestJson(basePath + "api/git/status", { cache: "no-store" }).then(function (status) {
     if (statusBasePath !== basePath) return status;
     currentStatus = status;
+    store.set({ clayControlGitView: status.controlView ? Object.assign({ projectSlug: store.get('currentSlug') }, status.controlView) : null });
     if (expandedFileActionsPath && !status.files.some(function (file) { return file.path === expandedFileActionsPath; })) {
       expandedFileActionsPath = null;
     }

package/lib/public/modules/icon-strip-tooltip.js

@@ -81,7 +81,8 @@ export function showIconTooltipHtml(el, html, options) {
 export function bindIconTooltip(el, resolveMetadata) {
   function show() {
     var metadata = tooltipMetadata(typeof resolveMetadata === "function" ? resolveMetadata() : resolveMetadata);
-    showIconTooltip(el, metadata.text || "", metadata);
+    if (!metadata.text) { hideIconTooltip(); return; }
+    showIconTooltip(el, metadata.text, metadata);
   }
   el.addEventListener("mouseenter", show);
   el.addEventListener("focus", show);

package/lib/public/modules/input.js

@@ -1,3 +1,5 @@
+import { contextualAccessReference } from './contextual-mate-context.js';
+import { contextualScreenReference } from './contextual-clay-session.js';
 import { stopSTT } from './stt-controller.js';
 import { expectCreatedSession } from './session-create.js';
 import { hasRecordedSpeechFor, requestRecordedSend } from './stt-recording.js';
@@ -120,6 +122,7 @@ function showPreThinkingForTurn() {
 
 // --- Send ---
 export function sendMessage() {
+  if (store.get('contextualWriterSuspended')) return;
   if (ctx && requestRecordedSend(ctx.inputEl, sendMessage)) return;
   stopSTT();
   // Debate ended mode intercept: route to resume handler
@@ -349,7 +352,9 @@ export function sendMessage() {
     return;
   }
 
+  var screenReference = contextualScreenReference();
   var payload = { type: "message", text: text || "" };
+  if (screenReference) payload.contextualSnapshot = screenReference;
   if (images.length > 0) {
     payload.images = images;
   }
@@ -359,6 +364,8 @@ export function sendMessage() {
   // Include selected vendor for session binding (server uses on first message)
   var _selVendor = store.get("currentVendor") || null;
   if (_selVendor) payload.vendor = _selVendor;
+  var contextRef = contextualAccessReference();
+  if (contextRef) payload.mateContextRef = contextRef;
   if (!prepareAutonomousPayload(payload)) return;
   ctx.currentMsgTs = Date.now();
   sendAcknowledgedMessage(payload);
@@ -448,7 +455,9 @@ export function sendShellResultToAgent(msg) {
 
 export function autoResize() {
   ctx.inputEl.style.height = "auto";
-  ctx.inputEl.style.height = Math.min(ctx.inputEl.scrollHeight, 120) + "px";
+  var border = ctx.inputEl.offsetHeight - ctx.inputEl.clientHeight;
+  ctx.inputEl.style.height = Math.min(ctx.inputEl.scrollHeight + border, 120) + "px";
+  ctx.inputEl.style.overflowY = ctx.inputEl.scrollHeight > ctx.inputEl.clientHeight ? "auto" : "hidden";
   // Defensive: sync send/stop button whenever input size changes
   if (ctx.processing && ctx.setSendBtnMode) {
     ctx.setSendBtnMode(hasSendableContent() ? "send" : "stop");
@@ -533,6 +542,30 @@ function removePendingImage(idx) {
   renderInputPreviews();
 }
 
+// Move composer ownership between two authenticated views of the same session.
+export function takeComposerDraft() {
+  if (uploadingCount) throw new Error('Wait for attachments to finish uploading before opening Clay.');
+  if (store.get('speechActive') || hasRecordedSpeechFor(ctx.inputEl)) throw new Error('Finish or discard the voice recording before changing Clay views.');
+  var input = ctx.inputEl;
+  var draft = { text: input.value, start: input.selectionStart, end: input.selectionEnd, direction: input.selectionDirection, images: pendingImages, pastes: pendingPastes, files: pendingFiles, delay: scheduleDelayMs };
+  input.value = '';
+  clearPendingImages();
+  clearScheduleDelay();
+  autoResize();
+  return draft;
+}
+export function restoreComposerDraft(draft) {
+  if (!draft) return;
+  pendingImages = draft.images || [];
+  pendingPastes = draft.pastes || [];
+  pendingFiles = draft.files || [];
+  ctx.inputEl.value = draft.text || '';
+  ctx.inputEl.setSelectionRange(draft.start || 0, draft.end || 0, draft.direction || 'none');
+  setScheduleDelayMs(draft.delay || 0);
+  renderInputPreviews();
+  autoResize();
+}
+
 export function clearPendingImages() {
   pendingImages = [];
   pendingPastes = [];
@@ -840,6 +873,7 @@ function sendInputSync() {
 }
 
 export function handleInputSync(text) {
+  if (store.get('contextualWriterSuspended')) return;
   isRemoteInput = true;
   ctx.inputEl.value = text;
   autoResize();

package/lib/public/modules/issues-render.js

@@ -1,3 +1,4 @@
+import { store } from './store.js';
 import { githubWorkMarkup } from './session-github.js';
 import { issueGithubAction } from './issues-github.js';
 import { escapeHtml } from './utils.js';
@@ -18,7 +19,7 @@ export function renderIssueList(result) {
     var meta = [authorLine(entry), relativeTime(entry.updatedAt || entry.createdAt)];
     if (entry.revision > 1) meta.push('v' + entry.revision);
     if (entry.commentCount) meta.push(entry.commentCount + (entry.commentCount === 1 ? ' comment' : ' comments'));
-    return '<button type="button" class="issue-row" data-open-issue="' + esc(entry.ref) + '">' +
+    return '<button type="button" class="issue-row" data-control-runtime="' + esc(store.get("controlRuntimeId")) + '" data-control-revision="' + esc(entry.revision) + '" data-open-issue="' + esc(entry.ref) + '">' +
       '<div class="issue-row-head"><span class="issue-type">' + esc(entry.type) + '</span>' + priorityChip(entry.priority) + '<strong>' + esc(entry.title) + '</strong></div>' +
       (entry.summary ? '<p>' + esc(entry.summary) + '</p>' : '') +
       '<div class="issue-row-meta">' + statusChip(entry.status) + '<span>' + esc(meta.filter(Boolean).join(' · ')) + '</span></div></button>';
@@ -35,7 +36,7 @@ export function renderIssueDetail(entry) {
   var closed = entry.status === 'resolved' || entry.status === 'closed';
   var time = entry.updatedAt || entry.createdAt;
   var byline = [authorLine(entry), time ? new Date(time).toLocaleString() : '', 'v' + entry.revision].filter(Boolean).join(' · ');
-  return '<article class="issue-detail"><div class="issue-doc-chips"><span class="issue-type">' + esc(entry.type) + '</span>' + priorityChip(entry.priority) + statusChip(entry.status) + '</div>' +
+  return '<article class="issue-detail" data-control-ref="' + esc(entry.ref) + '" data-control-runtime="' + esc(store.get("controlRuntimeId")) + '" data-control-revision="' + esc(entry.revision) + '"><div class="issue-doc-chips"><span class="issue-type">' + esc(entry.type) + '</span>' + priorityChip(entry.priority) + statusChip(entry.status) + '</div>' +
     githubWorkMarkup(entry, true) +
     '<h2 class="issue-doc-title">' + esc(entry.title) + '</h2>' + prose(entry.summary, 'issue-doc-summary') + '<div class="issue-byline">' + esc(byline) + '</div>' +
     '<div class="issue-actions">' + action('data-issue-work', 'play', 'Start work', ' class="issue-primary"' + (closed ? ' disabled title="Reopen this issue to start work"' : '')) +