clay-server 5.2.0-beta.1 → 5.2.0-beta.11

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

@@ -0,0 +1,117 @@
+import { store } from './store.js';
+import { getWs } from './ws-ref.js';
+import { contextualFrame } from './contextual-mate-identity.js';
+
+function identity(frame) {
+  try { return frame && frame.conversation && frame.conversation.identity(); } catch (error) { return null; }
+}
+function contextKey(frame, canonical) {
+  var current = identity(frame);
+  return JSON.stringify([store.get('currentSlug'), store.get('activeSessionId'), store.get('sessionOriginId'), store.get('activeProjectSlug'), store.get('sessionActivatedProjectSlug'), store.get('replayingHistory'), (store.get('contextualClay') || {}).mode, store.get('homeShellVisible'), store.get('projectsHubVisible'), store.get('dmMode'), store.get('rightWorkbenchOwner'), store.get('homeSubSurface'), store.get('rightWorkbenchRevision'), store.get('myUserId'), store.get('connected'), current && current.mateId, current && current.sessionId, current && (canonical ? current.connected : current.ready), canonical && current && current.sessionOriginId]);
+}
+export function updateMateContext(surface, mate, frame, snapshot) {
+  var current = identity(frame), ws = getWs(), key = contextKey(frame, mate && mate.builtinKey === 'clay'), prepared = store.get('contextualPrepared');
+  var canonical = mate && mate.builtinKey === 'clay';
+  var capabilities = surface.querySelector('.contextual-capabilities');
+  capabilities.hidden = !canonical;
+  capabilities.setAttribute('aria-label', 'Clay capabilities');
+  capabilities.textContent = "I can control Clay Studio for you—manage projects, coordinate work, set up schedules, and navigate your workspace. Just tell me what you’d like done.";
+  var privateWorkspace = (store.get('currentSlug') || '').indexOf('mate-') === 0;
+  var parentReady = store.get('activeProjectSlug') === store.get('currentSlug') && store.get('sessionActivatedProjectSlug') === store.get('currentSlug') && !store.get('replayingHistory');
+  var available = (store.get('contextualClay') || {}).mode === 'popover' && parentReady && !canonical && !privateWorkspace && current && current.ready && store.get('connected') && !store.get('homeShellVisible') && !store.get('projectsHubVisible') && !store.get('dmMode') && !store.get('rightWorkbenchOwner') && ws && ws.readyState === 1;
+  var changed = !prepared || prepared.key !== key || prepared.socket !== ws;
+  if (changed) {
+    var requestId = 'context-' + crypto.randomUUID();
+    prepared = { key: key, requestId: requestId, socket: ws, mateId: current && current.mateId, canonical: !!canonical, status: available ? 'preparing' : 'unavailable' };
+  }
+  // Stamp the reference before publishing a new preparation: store subscribers
+  // may render synchronously, and the composer must never see the prior view ID.
+  snapshot = Object.assign({}, snapshot, { viewId: prepared.requestId });
+  surface.dataset.screenReference = JSON.stringify(snapshot);
+  if (changed) {
+    store.set({ contextualPrepared: prepared });
+    if (ws && ws.readyState === 1) ws.send(JSON.stringify({ type: 'mate_context_prepare', requestId: requestId, available: !!available, mateId: current && current.mateId, sessionId: current && current.sessionId }));
+  }
+  var shared = ((store.get('contextualSubmitted') || {})[mate && mate.id]);
+  var ready = prepared.status === 'ready' && prepared.expiresAt > Date.now();
+  var label = surface.querySelector('[data-clay-context]');
+  var detail = surface.querySelector('.contextual-clay-context p');
+  var summary = ready ? prepared.summary.project + ' / ' + prepared.summary.conversation : null;
+  var projectName = (ready && prepared.summary.project) || snapshot.projectTitle || snapshot.screen || 'Current view';
+  if (canonical) {
+    var currentSummary = (snapshot.projectTitle || snapshot.screen || 'Current view') + (snapshot.conversationTitle ? ' / ' + snapshot.conversationTitle : '');
+    var disconnected = !store.get('connected') || current && current.connected === false;
+    var sameSnapshot = shared && shared.viewId === prepared.requestId && shared.summary.project + (snapshot.conversationTitle ? ' / ' + shared.summary.conversation : '') === currentSummary;
+    var contextStatus = disconnected ? 'Disconnected' : current && current.available === false ? 'Unavailable' : !current || !current.ready ? 'Preparing' : sameSnapshot ? 'Shared' : shared ? 'New view' : 'Next message';
+    detail.textContent = "I can help manage your projects, coordinate work with Drivers, and use Studio’s tools. I’ll ask you to review actions when needed.\n"
+      + 'Current view: ' + currentSummary + '. ' + (disconnected ? 'Reconnect before sharing a new snapshot. ' : !current || !current.ready ? 'Wait for this conversation before sharing a new snapshot. ' : sameSnapshot ? 'This metadata snapshot was shared with your last message. Your next message captures the current view again. ' : 'Your next message includes this metadata snapshot. ')
+      + 'Clay receives project and conversation metadata, not continuous screen capture. Its authenticated product tools inspect supported objects separately; changes require their existing review.';
+  } else {
+    contextStatus = !store.get('connected') || current && current.connected === false ? 'Disconnected' : current && current.available === false ? 'Unavailable' : current && !current.ready || prepared.status === 'preparing' ? 'Preparing' : ready ? (shared && shared.viewId === prepared.requestId ? 'Shared' : shared ? 'New view' : 'Next message') : 'Unavailable';
+    detail.textContent = ready ? (shared && shared.viewId === prepared.requestId ? 'Shared with your last message: ' : 'With your next message: ') + summary + '. This Mate can read up to 20 text turns from this selected conversation and request to open it in this window after your review. Tool results, attachments and hidden entries are excluded.' : 'Current view: ' + projectName + '. This view has no supported conversation context. Open an accessible project conversation to share it with your next message.';
+    detail.textContent += '\nNo continuous screen capture. Issues, documents, other tabs, files and settings are unavailable through this context.';
+  }
+  if (prepared.status === 'expired' && !canonical) { contextStatus = 'Expired'; detail.textContent = 'This five-minute context has expired. Close and reopen this Mate to prepare a fresh snapshot. No previous navigation request will replay.'; }
+  if (shared) detail.textContent += '\nLast submitted: ' + shared.summary.project + ' / ' + shared.summary.conversation + ((canonical ? sameSnapshot : shared.viewId === prepared.requestId) ? '.' : canonical ? '. The view or connection has changed; that snapshot is stale.' : '. Your view has changed; that context is stale.');
+  var projectLabel = label.querySelector('[data-context-project]');
+  if (!projectLabel) { projectLabel = document.createElement('span'); projectLabel.dataset.contextProject = ''; var statusLabel = document.createElement('span'); statusLabel.dataset.contextStatus = ''; label.replaceChildren(projectLabel, statusLabel); }
+  projectLabel.textContent = projectName;
+  label.querySelector('[data-context-status]').textContent = ' · ' + contextStatus;
+  label.title = label.textContent;
+  surface.contextReference = function (source, session) {
+    var live = store.get('contextualPrepared');
+    if (!frame || frame.hidden || frame.contentWindow !== source || !session || !current || session.mateId !== current.mateId || session.sessionId !== current.sessionId || !session.ready || !live || live.key !== contextKey(frame, canonical) || live.socket !== getWs() || live.status !== 'ready' || live.expiresAt <= Date.now()) return null;
+    return live.contextRef;
+  };
+}
+export function handleMateContextMessage(msg) {
+  if (msg.type === 'mate_context_prepared') {
+    var pending = store.get('contextualPrepared');
+    if (pending && pending.requestId === msg.requestId && pending.socket === getWs() && pending.key === contextKey(contextualFrame(), pending.canonical)) {
+      store.set({ contextualPrepared: Object.assign({}, pending, msg, { status: msg.contextRef ? 'ready' : 'unavailable' }) });
+      if (msg.contextRef) setTimeout(function () {
+        var current = store.get('contextualPrepared');
+        if (current && current.contextRef === msg.contextRef) store.set({ contextualPrepared: Object.assign({}, current, { status: 'expired' }) });
+      }, Math.max(0, msg.expiresAt - Date.now()));
+    }
+    return true;
+  }
+  if ((msg.type === 'message_ack' || msg.type === 'user_message') && window.parent !== window && window.frameElement && window.frameElement.dataset.canonical === 'true') {
+    var recorded = msg.type === 'message_ack' ? msg.message : msg;
+    var outbound = (store.get('contextualSnapshotSubmissions') || []).find(function (item) { return item.clientMessageId === msg.clientMessageId; });
+    if (!outbound || outbound.confirmed || outbound.accountId !== (store.get('myUserId') || '_default') || !recorded || recorded.clientMessageId !== outbound.clientMessageId || !recorded.contextualSnapshot || msg.type === 'message_ack' && (msg.projectSlug !== outbound.projectSlug || String(msg.sessionId) !== String(outbound.sessionId)) || recorded.projectSlug !== outbound.projectSlug || String(recorded.sessionId) !== String(outbound.sessionId) || recorded.sessionOriginId !== outbound.sessionOriginId || recorded.from && recorded.from !== outbound.accountId || JSON.stringify(recorded.contextualSnapshot) !== JSON.stringify(outbound.snapshot)) return false;
+    var snapshot = recorded.contextualSnapshot;
+    store.set({ contextualSnapshotSubmissions: store.get('contextualSnapshotSubmissions').map(function (item) { return item === outbound ? Object.assign({}, item, { confirmed: true }) : item; }) });
+    try {
+      var host = window.parent.document.getElementById('contextual-clay');
+      if (host) host.dispatchEvent(new window.parent.CustomEvent('contextual-context-submitted', { detail: { source: window, message: { status: 'submitted', canonical: true, clientMessageId: msg.clientMessageId, viewId: snapshot.viewId, summary: { project: snapshot.projectTitle || snapshot.projectSlug || 'Home', conversation: snapshot.conversationTitle || snapshot.screen } } } }));
+    } catch (error) { /* A disconnected authentication view cannot share metadata. */ }
+    return false;
+  }
+  if (msg.type !== 'mate_context_shared') return false;
+  try {
+    var surface = window.parent.document.getElementById('contextual-clay');
+    if (surface && window.frameElement && surface.contains(window.frameElement)) surface.dispatchEvent(new window.parent.CustomEvent('contextual-context-submitted', { detail: { source: window, message: msg } }));
+  } catch (error) { /* A disconnected authentication view cannot share context. */ }
+  return true;
+}
+export function recordMateContextSubmission(surface, event) {
+  var frame = Array.from(surface.querySelectorAll('iframe')).find(function (item) { return item.contentWindow === event.detail.source; });
+  var pending = store.get('contextualPrepared'), msg = event.detail.message;
+  if (!frame || frame.dataset.ownerId !== (store.get('myUserId') || '') || (!msg.canonical && frame.hidden) || !pending) return;
+  if (msg.status === 'unavailable') {
+    if (pending.mateId === frame.dataset.mateId) store.set({ contextualPrepared: Object.assign({}, pending, { status: 'unavailable' }) });
+    return;
+  }
+  if (msg.status !== 'submitted' || !msg.summary || (msg.canonical ? frame.dataset.canonical !== 'true' || typeof msg.viewId !== 'string' : msg.contextRef !== pending.contextRef)) return;
+  var submitted = Object.assign({}, store.get('contextualSubmitted'));
+  submitted[frame.dataset.mateId] = { key: msg.canonical ? null : pending.key, viewId: msg.canonical ? msg.viewId : pending.requestId, summary: msg.summary };
+  store.set({ contextualSubmitted: submitted });
+}
+export function contextualAccessReference() {
+  if (window.parent === window || !store.get('paneMode')) return null;
+  try {
+    var surface = window.parent.document.getElementById('contextual-clay');
+    return surface && surface.contextReference && surface.contextReference(window, { mateId: window.frameElement.dataset.mateId, sessionId: store.get('paneSessionId'), ready: store.get('contextualSessionReady') && store.get('connected') });
+  } catch (error) { return null; }
+}

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

@@ -0,0 +1,40 @@
+import { store } from './store.js';
+import { contextualMate, contextualTrigger } from './contextual-mate-identity.js';
+import { getHomeMateName } from './home-mate-selection.js';
+
+export function renderContextualMateHint() {
+  var state = store.get('contextualClay') || {};
+  var mate = contextualMate(state.mateId);
+  var active = state.mode === 'popover' && mate;
+  var narrow = window.matchMedia('(max-width: 768px)').matches;
+  var moved = document.querySelector('.contextual-mate-mobile-trigger');
+  if (moved && (!active || !narrow || moved.dataset.mateId !== mate.id)) {
+    moved.classList.remove('contextual-mate-mobile-trigger');
+    document.getElementById('icon-strip-projects').appendChild(moved);
+  }
+  var anchor = active && contextualTrigger(mate.id);
+  if (anchor && narrow && mate.builtinKey !== 'clay') {
+    anchor.classList.add('contextual-mate-mobile-trigger'); if (anchor.parentNode !== document.body) document.body.appendChild(anchor);
+  }
+  document.body.classList.toggle('contextual-mate-hint-mobile', !!active && narrow);
+  document.body.classList.toggle('contextual-mate-ordinary-mobile', !!active && narrow && mate.builtinKey !== 'clay');
+  document.querySelectorAll('[aria-describedby="contextual-mate-hint"]').forEach(function (item) { if (item !== anchor) item.removeAttribute('aria-describedby'); });
+  var hint = document.getElementById('contextual-mate-hint');
+  if (!hint || !active || !anchor || !anchor.getClientRects().length) { if (hint) hint.hidden = true; return null; }
+  anchor.setAttribute('aria-describedby', hint.id);
+  var name = getHomeMateName(mate);
+  hint.textContent = (window.matchMedia('(pointer: coarse)').matches ? 'Tap' : 'Click') + ' again to open ' + name;
+  hint.title = hint.textContent;
+  hint.setAttribute('aria-label', 'Open ' + name + ' workspace');
+  hint.hidden = false;
+  var rect = anchor.getBoundingClientRect();
+  hint.style.maxWidth = (narrow ? window.innerWidth - 64 : Math.min(260, window.innerWidth - rect.right - 24)) + 'px';
+  hint.style.left = (narrow ? 50 : rect.right + 8) + 'px';
+  hint.style.top = (narrow ? 8 : Math.max(8, Math.min(window.innerHeight - 38, rect.top + (rect.height - 28) / 2))) + 'px';
+  return hint.getBoundingClientRect();
+}
+export function initContextualMateHint(activate) {
+  var hint = document.createElement('button'); hint.type = 'button'; hint.id = 'contextual-mate-hint'; hint.hidden = true;
+  hint.addEventListener('click', function () { activate((store.get('contextualClay') || {}).mateId); });
+  document.body.appendChild(hint);
+}

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

@@ -0,0 +1,23 @@
+import { store } from './store.js';
+
+export function contextualMate(id) {
+  var mate = (store.get('cachedMatesList') || []).find(function (item) { return item && item.id === id; });
+  if (!mate || mate.archived || mate.contentAccess === false || mate.accessible === false) return null;
+  var owner = store.get('myUserId');
+  if (owner && mate.createdBy && mate.createdBy !== owner) return null;
+  var project = (store.get('projectsHubList') || []).find(function (item) { return item.slug === 'mate-' + id; });
+  if (project && project.contentAccess === false) return null;
+  return mate;
+}
+export function contextualMateStamp(mate) { return JSON.stringify([mate.id, mate.createdBy || null, mate.createdAt || null, mate.builtinKey || null]); }
+export function contextualFrame(id, sessionId) {
+  var mateId = id || (store.get('contextualClay') || {}).mateId;
+  var current = store.get('contextualClay') || {};
+  if (!sessionId && current.mateId === mateId && current.startingAsk) return null;
+  var selected = sessionId || (current.mateId === mateId && current.sessionId) || (store.get('contextualSessionSelection') || {})[mateId];
+  return Array.from(document.querySelectorAll('#contextual-clay iframe')).find(function (frame) { return frame.dataset.mateId === mateId && (!selected || String(selected) === frame.dataset.sessionId); }) || null;
+}
+export function contextualTrigger(id) {
+  var mate = contextualMate(id || (store.get('contextualClay') || {}).mateId);
+  return mate && mate.builtinKey !== 'clay' ? document.querySelector('.icon-strip-project-mate[data-mate-id="' + CSS.escape(mate.id) + '"]') : document.querySelector('.icon-strip-brand');
+}

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/debate.js

@@ -58,6 +58,7 @@ function buildAvatarUrl(meta) {
   return mateAvatarUrl({
     id: meta.mateId,
     profile: {
+      avatarCatalogId: meta.avatarCatalogId || "",
       avatarStyle: meta.avatarStyle || "imprint",
       avatarSeed: meta.avatarSeed || meta.mateId || "mate",
       avatarColor: meta.avatarColor || "#5857fc",

package/lib/public/modules/default-ai.js

@@ -110,6 +110,13 @@ function inlineCurrentSelection(state, draft) {
   return state.preference || state.selection || draft || {};
 }
 
+function updateDraft(draft) {
+  var state = store.get('defaultAiState') || {};
+  var saved = state.preference || state.selection || {};
+  var dirty = ['vendor', 'model', 'effort'].some(function (key) {return (draft[key] || '') !== (saved[key] || '');});
+  store.set({defaultAiDraft:draft, defaultAiDraftDirty:dirty});
+}
+
 function renderInlineSummary() {
   var state = store.get("defaultAiState") || {};
   var draft = store.get("defaultAiDraft") || {};
@@ -209,16 +216,16 @@ function render() {
   effort.disabled = !models.length || state.saving === true;
 
   vendor.addEventListener("change", function () {
-    store.set({ defaultAiDraft: { vendor: vendor.value, model: "", effort: "" }, defaultAiDraftDirty: true });
+    updateDraft({ vendor: vendor.value, model: "", effort: "" });
     requestCatalog(vendor.value);
     render();
   });
   model.addEventListener("change", function () {
-    store.set({ defaultAiDraft: { vendor: vendor.value, model: model.value, effort: "" }, defaultAiDraftDirty: true });
+    updateDraft({ vendor: vendor.value, model: model.value, effort: "" });
     render();
   });
   effort.addEventListener("change", function () {
-    store.set({ defaultAiDraft: { vendor: vendor.value, model: model.value, effort: effort.value }, defaultAiDraftDirty: true });
+    updateDraft({ vendor: vendor.value, model: model.value, effort: effort.value });
     render();
   });
   addFieldLabel("Provider", vendor);
@@ -304,6 +311,7 @@ function applyCatalogMessage(msg, state) {
     draft = Object.assign({}, draft, { model: msg.selection.model, effort: msg.selection.effort || "" });
   }
   store.set({ defaultAiState: next, defaultAiDraft: draft });
+  updateDraft(draft);
 }
 
 function applyStateMessage(msg, state) {

package/lib/public/modules/elicitation-form.js

@@ -4,6 +4,8 @@
 import { escapeHtml } from './utils.js';
 import { iconHtml } from './icons.js';
 import { getWs } from './ws-ref.js';
+import { store } from './store.js';
+import { currentPaneReview } from './pane-binding.js';
 import { fieldInfo, patternIsBounded, validateForm } from './elicitation-schema.js';
 
 var UNSET = "__clay_unset__";
@@ -154,12 +156,14 @@ function showFormError(container, message) {
 }
 
 function send(container, action, content, onSent) {
+  if (!currentPaneReview(container)) return false;
   var ws = getWs();
   if (!ws || ws.readyState !== 1) {
     showFormError(container, "Not connected. Try again when the connection is restored.");
     return false;
   }
   var msg = { type: "elicitation_response", requestId: container.dataset.requestId, action: action };
+  if (container.paneBinding) msg.paneBinding = container.paneBinding;
   if (action === "accept") msg.content = content;
   ws.send(JSON.stringify(msg));
   setBusy(container, true);
@@ -177,6 +181,7 @@ function actionButton(label, className, handler) {
 
 export function buildElicitationCard(msg, onSent) {
   var container = el("div", "permission-container elicitation-container");
+  container.paneBinding = store.get('panePendingBinding') || store.get('paneCommittedBinding') || null;
   container.dataset.requestId = msg.requestId;
   var header = el("div", "permission-header");
   header.innerHTML = '<span class="permission-icon">' + iconHtml("key") + '</span>' +