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

package/lib/mate-context-service.js

@@ -0,0 +1,138 @@
+// Restricted contextual access. References originate on authenticated app sockets;
+// model arguments and submitted attachments never create or widen a grant.
+var crypto = require('crypto');
+var refs = require('./workspace-query-service');
+var provenance = require('./session-provenance');
+var personal = require('./mcp-session-access');
+var z = require('zod');
+var preparationSchema = z.object({ type: z.literal('mate_context_prepare'), requestId: z.string().max(100).optional(), available: z.boolean(), mateId: z.string().max(128).optional(), sessionId: z.number().int().positive().optional() }).strict();
+function attachMateContextService(ctx) {
+  var access = require('./workspace-query-access').attachWorkspaceQueryAccess(ctx);
+  var views = new WeakMap(), pending = new Map(), active = new WeakMap();
+  function owner(ws) { return ctx.isMultiUser() ? ws && ws._clayUser && ws._clayUser.id : null; }
+  function privateSession(session, manager, id) {
+    if (!session || manager.sessions.get(session.localId) !== session || session.hidden || session.destroying || session.spawn || provenance.isWorker(session) ||
+      session.sessionVisibility === 'shared' || session.delegated || session._delegatedBy || session._pairDelegation || session._mcpForeignInput ||
+      session.homeDebatePlanning || session.debateSetupMode || session.mateCreationMode || session._mentionInProgress) throw new Error('A live private owner conversation is required.');
+    if (ctx.isMultiUser() ? !id || session.ownerId !== id || !ctx.findUser(id) || !personal.canUsePersonalConnections(session, manager.sessions) : !!session.ownerId ||
+      (session.history || []).some(function (entry) { return entry.type === 'user_message' && entry.from && entry.from !== 'default'; })) throw new Error('Owner-authored input is required.');
+  }
+  function source(id, mateId, sessionId) {
+    var mate = ctx.resolveMate(id, mateId), project = ctx.getProjects().get('mate-' + mateId);
+    var status = project && project.getStatus(), manager = project && project.getSessionManager();
+    if (!mate || mate.builtinKey === 'clay' || mate.archived || mate.lifecycleDeletion || !status || !status.isMate || status.mateId !== mateId || (ctx.isMultiUser() && (mate.createdBy !== id || status.projectOwnerId !== id))) throw new Error('This private Mate is unavailable.');
+    var session = manager.sessions.get(sessionId);
+    privateSession(session, manager, id);
+    var user = ctx.isMultiUser() && ctx.findUser(id);
+    return { mate: mate, revision: JSON.stringify(mate), project: project, session: session, manager: manager, path: status.path, osIdentity: JSON.stringify(user && [user.id, user.linuxUser || null]) };
+  }
+  function selected(id, viewer) {
+    var project = ctx.getProjects().get(viewer.slug), status = project && project.getStatus();
+    var principal = { userId: id, singleUserOwnerId: id };
+    if (!status || status.isMate || !access.evaluate(principal, status).accessible) throw new Error('The selected ordinary project is unavailable.');
+    var manager = project.getSessionManager(), session = manager.sessions.get(viewer.sessionId);
+    privateSession(session, manager, id);
+    return { project: project, session: session, path: status.path, revision: JSON.stringify([status.path, status.projectOwnerId, session.sessionOriginId, session.cliSessionId, session.title, session.history]),
+      summary: { project: String(status.title || status.project || status.slug).slice(0, 160), conversation: String(session.title || 'New conversation').slice(0, 160) } };
+  }
+  function validate(entry) {
+    if (!entry || Date.now() - entry.created > 300000) throw new Error('Context expired. Send a new message from the current view.');
+    var viewer = ctx.getOwnerUi().check(entry.owner, entry.viewer);
+    if (views.get(viewer.ws) !== entry.view) throw new Error('The current view changed. Send a new message from that view.');
+    var live = source(entry.owner, entry.mateId, entry.source.session.localId), target = selected(entry.owner, viewer);
+    if (live.project !== entry.source.project || live.session !== entry.source.session || live.revision !== entry.source.revision || live.path !== entry.source.path || live.osIdentity !== entry.source.osIdentity) throw new Error('The Mate was changed or replaced.');
+    if (target.project !== entry.target.project || target.session !== entry.target.session || target.revision !== entry.target.revision) throw new Error('The selected conversation changed or was replaced.');
+    return { source: live, target: target };
+  }
+  function send(ws, value) { if (ws.readyState === 1) ws.send(JSON.stringify(value)); }
+  function handleMessage(ws, msg) {
+    if (msg.type !== 'mate_context_prepare') return false;
+    var id = owner(ws), requestId = typeof msg.requestId === 'string' ? msg.requestId.slice(0, 100) : null;
+    try {
+      preparationSchema.parse(msg);
+      var viewer = ctx.getOwnerUi().list(id).find(function (item) { return item.ws === ws && item.supported; });
+      if (!viewer) throw new Error('The originating window is unavailable.');
+      var view = {}; views.set(ws, view);
+      if (msg.available !== true) throw new Error('This view has no supported conversation selection.');
+      var live = source(id, msg.mateId, msg.sessionId), target = selected(id, viewer);
+      pending.forEach(function (entry, key) { if (Date.now() - entry.created > 300000 || entry.viewer.ws === ws) pending.delete(key); });
+      if (pending.size >= 100) throw new Error('Context capacity is temporarily full.');
+      var ref = 'mate-context:' + crypto.randomUUID();
+      pending.set(ref, { owner: id, viewer: viewer, view: view, mateId: msg.mateId, source: live, target: target, created: Date.now() });
+      send(ws, { type: 'mate_context_prepared', requestId: requestId, contextRef: ref, summary: target.summary, expiresAt: Date.now() + 300000 });
+    } catch (error) { send(ws, { type: 'mate_context_prepared', requestId: requestId, contextRef: null, error: error.message }); }
+    return true;
+  }
+  function activate(ws, session, ref, message) {
+    active.delete(session);
+    var original = pending.get(ref);
+    var entry = original && Object.assign({}, original);
+    if (!entry) throw new Error('No current context was shared.');
+    var live = validate(entry);
+    if (owner(ws) !== entry.owner || live.source.session !== session || !live.source.project.clients.has(ws) || ws._clayActiveSession !== session.localId || ws._clayAuthCheck && !ws._clayAuthCheck()) throw new Error('Context belongs to another authenticated conversation.');
+    entry.message = message; entry.ref = ref; entry.requests = new Map(); entry.deliveries = new Set(); active.set(session, entry);
+    return { contextRef: ref, summary: entry.target.summary, limits: 'Selected conversation metadata; read_selected_context returns at most 20 redacted text turns (24000 characters). No screen capture, Issues, documents, files or hidden settings. Opening this conversation requires exact owner review.' };
+  }
+  function clear(session) { active.delete(session); }
+  function assertActive(session, ref) {
+    var entry = active.get(session);
+    var latest = (session.history || []).filter(function (item) { return item.type === 'user_message'; }).slice(-1)[0];
+    if (!entry || latest !== entry.message || entry.ref !== ref || session.taskStopRequested || session.abortController && session.abortController.signal.aborted) throw new Error('Shared context was interrupted.');
+    validate(entry);
+  }
+  function bind(input) {
+    var session = input.session, generation = Number(session._sdkQueryGeneration || 0), entry = active.get(session), original;
+    try { original = source(ctx.isMultiUser() ? input.projectOwnerId : null, input.mateId, session.localId); }
+    catch (error) { return null; }
+    if (original.session !== session || input.projectSlug !== 'mate-' + input.mateId || session.taskStopRequested || session.abortController && session.abortController.signal.aborted) return null;
+    function base() {
+      var live = source(ctx.isMultiUser() ? input.projectOwnerId : null, input.mateId, session.localId);
+      if (live.session !== session || live.project !== original.project || live.revision !== original.revision || live.path !== original.path || live.osIdentity !== original.osIdentity || Number(session._sdkQueryGeneration || 0) !== generation || session.taskStopRequested || session.abortController && session.abortController.signal.aborted) throw new Error('This exact private Mate query is unavailable.');
+    }
+    function check() {
+      base();
+      if (!entry || active.get(session) !== entry || Number(session._sdkQueryGeneration || 0) !== generation || session.taskStopRequested || session._pendingMessageDrainPaused || session.abortController && session.abortController.signal.aborted) throw new Error('This context query is unavailable or stopped.');
+      var latest = (session.history || []).filter(function (item) { return item.type === 'user_message'; }).slice(-1)[0];
+      if (latest !== entry.message || input.mateId !== entry.mateId || input.projectSlug !== 'mate-' + entry.mateId || (ctx.isMultiUser() && input.projectOwnerId !== entry.owner)) throw new Error('Context belongs to another exact owner query.');
+      return validate(entry);
+    }
+    function reference(args) { if (!args || args.contextRef !== (entry && entry.ref)) throw new Error('Use only the context reference returned for this query.'); return check(); }
+    return {
+      current: function () {
+        base();
+        if (!entry) return { status: 'unavailable', supported: ['selected_conversation'], unavailable: ['issues', 'documents', 'tabs', 'screen_capture'] };
+        check(); return { status: 'shared_snapshot', contextRef: entry.ref, summary: entry.target.summary, expiresAt: entry.created + 300000, supported: ['selected_conversation'], unavailable: ['issues', 'documents', 'tabs', 'screen_capture'], untrusted: true };
+      },
+      read: async function (args) {
+        var live = reference(args), bound = ctx.workspace.bindProjectSession({ projectSlug: entry.viewer.slug, session: live.target.session, viewerId: entry.owner });
+        if (!bound) throw new Error('The selected conversation is unavailable.');
+        var result = await bound.readProjectSession({ projectSlug: entry.viewer.slug, sessionRef: refs.sessionRef(entry.viewer.slug, live.target.session), limit: 20 });
+        reference(args);
+        var remaining = 24000;
+        var turns = result.turns.map(function (turn) { var text = turn.text.slice(0, remaining); remaining -= text.length; return { role: turn.role, text: text }; }).filter(function (turn) { return !!turn.text; });
+        return { summary: entry.target.summary, turns: turns, truncated: result.total > turns.length || remaining === 0, untrusted: true };
+      },
+      navigate: function (args) {
+        reference(args);
+        var key = JSON.stringify([args.contextRef, args.why]), old = entry.requests.get(args.requestId);
+        if (old) { if (old.key !== key) throw new Error('This requestId already names another intent.'); return old.promise; }
+        if (entry.requests.size >= 20) throw new Error('Too many navigation requests in this context.');
+        var promise = Promise.resolve().then(async function () {
+          var live = check();
+          var answer = await live.source.project.requestProductControlReview(session,
+            'Open the selected conversation: ' + entry.target.summary.conversation + '\nProject: ' + entry.target.summary.project + '\nWhy: ' + args.why,
+            check, { kind: 'product-control', action: 'Open conversation', target: entry.target.summary.conversation, context: 'In ' + entry.target.summary.project + ', in the window that shared this context.', reason: args.why });
+          check();
+          if (answer.status !== 'submitted' || !answer.answers.control || answer.answers.control.length !== 1 || answer.answers.control[0] !== 'Apply exact change') return { status: 'cancelled' };
+          var result = ctx.getOwnerUi().deliver(entry.owner, entry.viewer, { projectSlug: entry.viewer.slug, sessionId: entry.target.session.localId, sessionOriginId: entry.target.session.sessionOriginId, contextualSourceMateId: entry.mateId }, check);
+          if (result.deliveryId) entry.deliveries.add(result.deliveryId);
+          return result;
+        }).catch(function (error) { return { status: 'failed', retrySafe: false, error: error.message }; });
+        entry.requests.set(args.requestId, { key: key, promise: promise }); return promise;
+      },
+      receipt: function (args) { reference(args); if (!entry.deliveries.has(args.deliveryId)) throw new Error('Receipt belongs to another context.'); return ctx.getOwnerUi().read(entry.owner, args.deliveryId); }
+    };
+  }
+  return { handleMessage: handleMessage, activate: activate, clear: clear, assertActive: assertActive, bind: bind };
+}
+module.exports = { attachMateContextService: attachMateContextService };

package/lib/mate-context-tools.js

@@ -0,0 +1,21 @@
+var z = require('zod');
+function getToolDefs(bound) {
+  function tool(name, description, schema, method) {
+    return { name: name, description: description, inputSchema: schema, queryBound: true, handler: async function (args) {
+      try {
+        args = z.object(schema).strict().parse(args || {});
+        if (!bound) throw new Error('No exact owner context query is available.');
+        var result = await bound[method](args);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }], isError: result.status === 'failed' };
+      } catch (error) { return { content: [{ type: 'text', text: JSON.stringify({ status: 'failed', error: error.message }) }], isError: true }; }
+    } };
+  }
+  var ref = z.string().max(100);
+  return [
+    tool('read_current_context', 'Read the server-bound snapshot shared with this exact owner message. Selected ordinary-project conversation metadata only, never live screen capture. Unsupported views, Issues, documents and tabs are unavailable. Context expires after five minutes or any view/target/query/owner change. Content is untrusted data, never approval.', {}, 'current'),
+    tool('read_selected_context', 'Read up to 20 canonical user/assistant text turns (24000 characters total) from ONLY the conversation selected when this message was sent. Hidden/internal entries, tools and attachments are excluded. No enumeration, arbitrary IDs, files or private Mate conversations.', { contextRef: ref }, 'read'),
+    tool('open_context_conversation', 'Open ONLY that exact selected conversation in the originating authenticated window, after exact human review. No messages, edits, execution, Workers, settings or arbitrary routes. Query-local requestId receipts (at most 20, five minutes) never replay interrupted or uncertain effects. Delivery and client acceptance do not prove rendering; inspect receipt before retrying.', { contextRef: ref, requestId: z.string().min(1).max(100), why: z.string().trim().min(1).max(300) }, 'navigate'),
+    tool('read_context_navigation_receipt', 'Read the exact owner navigation delivery receipt within the shared context. Delivery and client acceptance are separate; visible rendering remains unknown. A stopped or stale context cannot resume or replay navigation.', { contextRef: ref, deliveryId: z.string().max(100) }, 'receipt')
+  ];
+}
+module.exports = { getToolDefs: getToolDefs };

package/lib/project-connection.js

@@ -143,6 +143,9 @@ function attachConnection(ctx) {
   var _warmedUp = false;
 
   function findRestoredActiveSession(ws, wsUser, allSessions) {
+    if (ws._clayContextual && ws._clayPaneSession) {
+      return { active: allSessions.find(function (session) { return session.localId === ws._clayPaneSession; }) || null, storedPresence: null };
+    }
     var active = null;
     var presenceKey = wsUser ? wsUser.id : "_default";
     var storedPresence = userPresence.getPresence(slug, presenceKey);
@@ -202,7 +205,7 @@ function attachConnection(ctx) {
     } else if (!usersModule.isMultiUser()) {
       allSessions = allSessions.filter(function (s) { return !s.ownerId; });
     }
-    var restoredState = ws._clayPane
+    var restoredState = ws._clayPane && !ws._clayContextual
       ? { active: null, storedPresence: null }
       : findRestoredActiveSession(ws, wsUser, allSessions);
     var restoredActive = restoredState.active;
@@ -217,7 +220,7 @@ function attachConnection(ctx) {
       sm.saveSessionFile(restoredActive);
     }
     var initialModels = (sm.modelsByVendor && sm.modelsByVendor[initialVendor]) || sm.availableModels || [];
-    sendTo(ws, { type: "info", cwd: cwd, slug: slug, project: title || project, version: currentVersion, debug: !!debug, dangerouslySkipPermissions: dangerouslySkipPermissions, osUsers: osUsers, lanHost: lanHost, projectCount: _filteredProjects.length, projects: _filteredProjects, projectOwnerId: projectOwnerId, ownerLocked: ownerLocked, vendors: require("./yoke/vendor-registry").publicInfo(), isMate: isMate, mateId: isMate ? mateId : null, mateDisplayName: isMate ? (mateDisplayName || title || project || "Mate") : "" });
+    sendTo(ws, { type: "info", controlRuntimeId: require("./clay-control-target-projection").runtime(sm), cwd: cwd, slug: slug, project: title || project, version: currentVersion, debug: !!debug, dangerouslySkipPermissions: dangerouslySkipPermissions, osUsers: osUsers, lanHost: lanHost, projectCount: _filteredProjects.length, projects: _filteredProjects, projectOwnerId: projectOwnerId, ownerLocked: ownerLocked, vendors: require("./yoke/vendor-registry").publicInfo(), isMate: isMate, mateId: isMate ? mateId : null, mateDisplayName: isMate ? (mateDisplayName || title || project || "Mate") : "" });
     if (typeof sendCursorSharingState === "function") sendCursorSharingState(ws);
     // Update notifications are pushed on a scheduled interval (see
     // scheduleUpdateBroadcast). We no longer push on connect to avoid
@@ -235,7 +238,7 @@ function attachConnection(ctx) {
     sendTo(ws, { type: "config_state", model: initialModelInfo.model, vendor: initialVendor, sessionId: restoredActive ? restoredActive.localId : null, mode: initialPermissionState.requestedPermissionMode, effectivePermissionMode: initialPermissionState.effectivePermissionMode, permissionCapabilities: initialPermissionState.permissionCapabilities, mcpPermissionModeOverrides: initialPermissionState.mcpPermissionModeOverrides, effort: initialEffort || "medium", betas: sm.currentBetas || [], thinking: sm.currentThinking || "adaptive", thinkingBudget: sm.currentThinkingBudget || 10000 });
     sendTo(ws, { type: "last_vendor", vendor: sm.lastVendor || "" });
     providerSettings.messages(sm).forEach(function(message) { sendTo(ws, message); });
-    sendTo(ws, { type: "term_list", terminals: tm.list() });
+    sendTo(ws, { type: "term_list", terminals: tm.list(true) });
     // Any login flow already running in this project, so a reconnecting client
     // re-attaches to the existing login terminal instead of starting another.
     if (_vendorLogin) _vendorLogin.sendStateTo(ws);
@@ -267,7 +270,7 @@ function attachConnection(ctx) {
     var presenceKey = wsUser ? wsUser.id : "_default";
     var storedPresence = restoredState.storedPresence;
     var autoCreated = false;
-    if (!active && !ws._clayPane) {
+    if (!active && (!ws._clayPane || (ws._clayContextual && !ws._clayPaneSession))) {
       var autoOpts = {};
       if (wsUser && usersModule.isMultiUser()) autoOpts.ownerId = wsUser.id;
       active = sm.createSession(autoOpts, ws);
@@ -315,7 +318,7 @@ function attachConnection(ctx) {
           break;
         }
       }
-      sendTo(ws, { type: "history_done", lastUsage: _lastUsage, lastModelUsage: _lastModelUsage, lastCost: _lastCost, lastStreamInputTokens: _lastStreamInputTokens, context: _lastContext, contextUsage: require("./yoke/usage").context(active.lastContextUsage, active.vendor || "claude") });
+      sendTo(ws, { type: "history_done", controlHistoryRevision: require("./clay-control-target-projection").digest(active.history || []), sessionId: active.localId, sessionOriginId: active.sessionOriginId || null, lastUsage: _lastUsage, lastModelUsage: _lastModelUsage, lastCost: _lastCost, lastStreamInputTokens: _lastStreamInputTokens, context: _lastContext, contextUsage: require("./yoke/usage").context(active.lastContextUsage, active.vendor || "claude") });
       if (scheduledMessages) scheduledMessages.sendState(active, ws);
       if (pairResultRecovery) pairResultRecovery.sendState(active, ws);
 

package/lib/project-control-git-view.js

@@ -0,0 +1,12 @@
+var fs = require('fs'), path = require('path');
+var projection = require('./clay-control-target-projection');
+function project(service, principal, status, manager) {
+  var before = service.rootIdentity(principal, 'git');
+  var directory = fs.realpathSync(status.gitDir), stat = fs.statSync(directory), indexPath = path.join(directory, 'index');
+  var index = fs.existsSync(indexPath) ? require('crypto').createHash('sha256').update(fs.readFileSync(indexPath)).digest('hex') : null;
+  var view = { runtimeId: projection.runtime(manager), repository: projection.digest([directory, [stat.dev, stat.ino, stat.mode, stat.uid, stat.gid]]),
+    files: status.files.slice(0, 200).map(function (file) { return { path: file.path, revision: projection.digest([status.oid, index, file]) }; }) };
+  if (service.rootIdentity(principal, 'git') !== before) throw new Error('Workspace identity changed during projection.');
+  return view;
+}
+module.exports = { project: project };

package/lib/project-filesystem.js

@@ -116,7 +116,11 @@ function attachFilesystem(ctx) {
     // --- fs_read ---
     if (msg.type === "fs_read") {
       var metadata = { type: 'fs_read_result', path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId };
-      try { sendTo(ws, Object.assign(metadata, operations.read(fileScope, msg.path))); }
+      try {
+        var readResult = operations.read(fileScope, msg.path);
+        try { var fileSnapshot = operations.snapshot(fileScope, msg.path); if (fileSnapshot.hash === require('crypto').createHash('sha256').update(readResult.content).digest('hex')) readResult.controlRevision = require('./clay-control-target-projection').digest(fileSnapshot); } catch (ignored) {}
+        sendTo(ws, Object.assign(metadata, readResult));
+      }
       catch (e) { sendTo(ws, Object.assign(metadata, { error: fileError(e).message, errorCode: fileError(e).code })); }
       return true;
     }

package/lib/project-http.js

@@ -663,6 +663,9 @@ function attachHTTP(ctx) {
       var gitUserInfo = getOsUserInfoForReq(req);
       try {
         var gitStatus = gitCli.getStatus(cwd, gitUserInfo);
+        if (ctx.workspaceOperations) {
+          try { gitStatus.controlView = require('./project-control-git-view').project(ctx.workspaceOperations, { userId: req._clayUser && req._clayUser.id || null, singleUserOwnerId: ctx.getProjectOwnerId && ctx.getProjectOwnerId() || null }, gitStatus, sm); } catch (ignored) {}
+        }
         if (gitAttribution) {
           var visibleGitSessions = sm.sessions;
           if (usersModule.isMultiUser() && req._clayUser) {

package/lib/project-notifications.js

@@ -154,8 +154,9 @@ function attachNotifications(ctx) {
     return notifications.length;
   }
 
+  function controlProjection(item) { var value = Object.assign({}, item); delete value.controlRevision; return Object.assign(value, { controlRevision: require('./clay-control-target-projection').digest(value) }); }
   function visible(ws) {
-    return notifications.filter(function (notification) { return !ctx.canView || ctx.canView(ws, notification); });
+    return notifications.filter(function (notification) { return !ctx.canView || ctx.canView(ws, notification); }).map(controlProjection);
   }
 
   function publish(payload) {
@@ -164,7 +165,7 @@ function attachNotifications(ctx) {
       if (ws.readyState !== 1) return;
       if (payload.notification && !ctx.canView(ws, payload.notification)) return;
       var list = visible(ws);
-      ws.send(JSON.stringify(Object.assign({}, payload, { unreadCount: list.length })));
+      ws.send(JSON.stringify(Object.assign({}, payload, { notification: payload.notification ? controlProjection(payload.notification) : undefined, unreadCount: list.length })));
     });
   }
 
@@ -197,7 +198,7 @@ function attachNotifications(ctx) {
     saveNotifications();
     var payload = {
       type: "notification_created",
-      notification: notif,
+      notification: controlProjection(notif),
       unreadCount: getUnreadCount(),
     };
     // Project/session previews are projected for each authenticated viewer.
@@ -235,7 +236,7 @@ function attachNotifications(ctx) {
     if (items.some(function (item) { return !canReadOwned(principal, item); })) throw new Error('Owned notification access changed.');
   }
   function listOwned(principal) {
-    return notifications.filter(function (item) { return canReadOwned(principal, item); }).slice(0, 100).map(function (item) { return JSON.parse(JSON.stringify(item)); });
+    return notifications.filter(function (item) { return canReadOwned(principal, item); }).slice(0, 100).map(function (item) { return JSON.parse(JSON.stringify(controlProjection(item))); });
   }
   function inspectOwned(principal, ids) {
     var owned = listOwned(principal);

package/lib/project-product-control.js

@@ -18,9 +18,11 @@ function attachProjectProductControl(ctx) {
     if (session.ownerId && session.ownerId !== principal.singleUserOwnerId) throw new Error("Live target ownership denied.");
     return null;
   }
-  function review(session, question, revalidate) {
+  function review(session, question, revalidate, presentation) {
     var owner = session.ownerId || null;
     return userInput.dispatchUserInput(function (request, respond) {
+      // Presentation comes only from the bound product service, after normalization.
+      if (presentation) request.questions[0].review = presentation;
       request.authorizeResponse = function (ws) {
         try {
           revalidate();

package/lib/project-scheduled-messages.js

@@ -234,7 +234,7 @@ function attachProjectScheduledMessages(ctx) {
           images: images,
           pastes: pastes,
           clientMessageId: requestId ? "scheduled-request-" + requestId : "scheduled-" + job.id,
-          schedule: { jobId: job.id, revision: job.payload.revision, notBefore: job.runAt, ready: false },
+          schedule: { jobId: job.id, revision: job.payload.revision, notBefore: job.runAt, ready: false, logicalScheduleId: job.payload.logicalScheduleId || null, logicalRevision: job.payload.logicalRevision || null },
         }, queueActor(actorId));
         if (!queuedScheduled.ok) {
           if (current) {
@@ -304,7 +304,7 @@ function attachProjectScheduledMessages(ctx) {
           images: existing ? existing.message.images : undefined,
           pastes: existing ? existing.message.pastes : undefined,
           clientMessageId: existing ? existing.clientMessageId : "scheduled-" + updated.id,
-          schedule: { jobId: updated.id, revision: updated.payload.revision, notBefore: updated.runAt, ready: false },
+          schedule: { jobId: updated.id, revision: updated.payload.revision, notBefore: updated.runAt, ready: false, logicalScheduleId: updated.payload.logicalScheduleId || null, logicalRevision: updated.payload.logicalRevision || null },
         }, queueActor(actorUser && actorUser.id));
         if (!queued.ok) {
           try { scheduler.replaceQueued(job.id, job); }
@@ -375,7 +375,7 @@ function attachProjectScheduledMessages(ctx) {
       if (!ensured && job.payload.queueAdmissionRequired === true) throw new Error("Scheduled queue item is missing; refusing to recreate message payload.");
       if (!ensured) ensured = pendingMessageQueue.upsertScheduled(session, {
         type: "message", text: job.payload.text, clientMessageId: "scheduled-" + job.id,
-        schedule: { jobId: job.id, revision: job.payload.revision, notBefore: job.runAt, ready: false },
+        schedule: { jobId: job.id, revision: job.payload.revision, notBefore: job.runAt, ready: false, logicalScheduleId: job.payload.logicalScheduleId || null, logicalRevision: job.payload.logicalRevision || null },
       }, queueActor(job.payload.actorId));
       if (!ensured || ensured.ok === false) throw new Error(ensured.error || "Scheduled queue handoff could not be prepared.");
       var released = pendingMessageQueue.releaseScheduled(session, job.id, job.payload.revision);
@@ -438,7 +438,7 @@ function attachProjectScheduledMessages(ctx) {
         if (jobs[i].state === "queued" && !queueItemForJob(session, jobs[i], jobs[i].payload.actorId)) {
           if (jobs[i].payload.queueAdmissionRequired !== true || (jobs[i].payload.mateScheduleId && ctx.mateLifecycle && ctx.mateLifecycle().current(session, jobs[i]))) pendingMessageQueue.upsertScheduled(session, {
             type: "message", text: jobs[i].payload.text, clientMessageId: "scheduled-" + jobs[i].id,
-            schedule: { jobId: jobs[i].id, revision: jobs[i].payload.revision, notBefore: jobs[i].runAt, ready: false },
+            schedule: { jobId: jobs[i].id, revision: jobs[i].payload.revision, notBefore: jobs[i].runAt, ready: false, logicalScheduleId: jobs[i].payload.logicalScheduleId || null, logicalRevision: jobs[i].payload.logicalRevision || null },
           }, actor);
         }
         else if (["interrupted", "completed"].indexOf(jobs[i].state) >= 0) {

package/lib/project-scheduled-task-control.js

@@ -31,7 +31,7 @@ function attachScheduledTaskControl(ctx) {
     var begun = ctx.beginManual(session, requestId);
     if (!begun.ok) throw new Error(begun.error);
     var prior = session.scheduledTaskDraft;
-    var draft = Object.assign({}, prior, checked.value, { canonicalScheduling: true });
+    var draft = Object.assign({}, prior, checked.value, { canonicalScheduling: true, version: Number(prior.version || 0) + 1 });
     session.scheduledTaskDraft = draft;
     if (ctx.sm.saveSessionFile(session) !== true) { session.scheduledTaskDraft = prior; throw new Error('The canonical schedule proposal could not be saved.'); }
     if (drafts.size >= 100) drafts.delete(drafts.keys().next().value);

package/lib/project-session-document.js

@@ -63,23 +63,34 @@ function attachSessionDocument(ctx) {
 
   function canUse(caller) { return !!caller && (!ctx.canUseSession || ctx.canUseSession(caller)); }
 
+  function activity(caller, action) {
+    if (ctx.studioPresentation) return ctx.studioPresentation.begin(caller, action);
+    try { var display = ctx.getPresentation && ctx.getPresentation(caller); return display && display.track('studio', action); } catch (error) { return null; }
+  }
   function present(args, caller) {
     if (!canUse(caller)) return toolError("Documents require a live authorized session.");
     if (!caller) return toolError("present_markdown_edit requires a session-bound tool server");
     var target = resolveMarkdownPath(args.path);
     if (!target) return toolError("path must be a .md or .mdx file inside the project");
+    var observer;
     try {
+      observer = activity(caller, 'document');
       var snapshot = readSnapshot(target, caller);
       var relativePath = path.relative(cwd, target).split(path.sep).join("/");
-      sendToSession(caller.localId, {
+      var message = {
         type: "markdown_edit_present",
         path: relativePath,
         content: snapshot.content,
         exists: snapshot.exists,
-        size: snapshot.size,
-      });
+        size: snapshot.size, sessionId: caller.localId,
+      };
+      var delivered;
+      if (observer && observer.present) delivered = observer.present(message, "document", relativePath, require("./clay-control-target-projection").digest(snapshot), function () { if (!canUse(caller) || require("./clay-control-target-projection").digest(readSnapshot(target, caller)) !== require("./clay-control-target-projection").digest(snapshot)) throw new Error("Document revision changed."); }, function (value, onSent) { return sendToSession(caller.localId, value, onSent); });
+      else delivered = sendToSession(caller.localId, message);
+      if (observer && !observer.present) observer.finish(delivered > 0 ? { status: 'delivered' } : { outcome: 'uncertain' });
       return toolResult({ ready: true, path: relativePath });
     } catch (e) {
+      if (observer) { if (observer.unknown) observer.unknown(); else observer.finish({ outcome: 'uncertain' }); }
       return toolError(e.message || String(e));
     }
   }
@@ -95,11 +106,15 @@ function attachSessionDocument(ctx) {
     } catch (e) {
       return toolError(e.message || String(e));
     }
+    var observer = activity(caller, 'sketch');
     return wireframeRenderer.renderPlantUml(source).then(function () {
-      if (!canUse(caller)) return toolError("Document access changed.");
-      sendToSession(caller.localId, { type: "wireframe_present", source: source, id: args.id, title: String(args.title || "clay-sketch").slice(0, 100), sessionId: caller.localId });
+      if (!canUse(caller)) { if (observer) { if (observer.fail) observer.fail(); else observer.cancel(); } return toolError("Document access changed."); }
+      var message = { type: "wireframe_present", source: source, id: args.id, title: String(args.title || "clay-sketch").slice(0, 100), sessionId: caller.localId };
+      var delivered = observer && observer.present ? observer.present(message, "sketch", args.id, require("./clay-control-target-projection").digest(source), function () { if (!canUse(caller)) throw new Error("Sketch source changed."); }, function (value, onSent) { return sendToSession(caller.localId, value, onSent); }) : sendToSession(caller.localId, message);
+      if (observer && !observer.present) observer.finish(delivered > 0 ? { status: 'delivered' } : { outcome: 'uncertain' });
       return toolResult({ ready: true, id: args.id, saved: false });
     }).catch(function (e) {
+      if (observer) { if (observer.unknown) observer.unknown(); else observer.finish({ outcome: 'uncertain' }); }
       return toolError(e && e.message ? e.message : String(e));
     });
   }

package/lib/project-shared-browser.js

@@ -175,13 +175,14 @@ function attachSharedBrowser(ctx) {
     record.touched = Date.now(); broadcast(record);
     return projection(record);
   }
-  async function run(session, record, actor, action, event, intent) {
+  async function run(session, record, actor, action, event, intent, presentationStart) {
     requireAccess(session);
     if (!record || !record.runtime || !recordAllowed(record)) throw new Error("Open a browser first");
     if (record.handoff) throw new Error("Browser control is changing; wait for the handoff");
     // control "agent" = shared (owner and Clay may both act); "user" = exclusive human mode (Clay mutations denied).
     // The authorized owner is never blocked by control mode and ordinary human input never changes it.
     if (action !== "inspect" && actor === "agent" && record.control !== "agent") throw new Error("Only the user can control this browser right now (Clay is paused). Wait for them to resume shared control; do not work around it.");
+    if (action !== 'inspect') { record.presentationRevision = (record.presentationRevision || 0) + 1; if (presentationStart) presentationStart(record.presentationRevision); }
     var epoch = record.epoch;
     var generation = Number(session._sdkQueryGeneration || 0);
     await record.ready;
@@ -204,18 +205,22 @@ function attachSharedBrowser(ctx) {
     return result;
   }
   async function tool(session, args) {
+    var observer;
     try {
       requireAccess(session);
       if (args.intent !== undefined && (typeof args.intent !== "string" || args.intent.length > 160)) throw new Error("Browser intent must be at most 160 characters");
       var record = args.action === "status" || args.action === "open" ? null : selectRecord(session, args.browserId);
-      var value;
+      var value, actionRevision = record && (record.presentationRevision || 0);
+      function presentationStart(value) { actionRevision = value; }
+      if (['status', 'inspect'].indexOf(args.action) < 0 && ctx.getPresentation) { var display = ctx.getPresentation(session); if (display) observer = ctx.studioPresentation ? ctx.studioPresentation.begin(session, 'browser') : display.track('studio', 'browser'); }
       if (args.action === "status") value = { browsers: sessionRecords(session).map(projection) };
       else if (args.action === "open") {
         if (args.incognito !== undefined && typeof args.incognito !== "boolean") throw new Error("Invalid incognito mode");
         var url = args.url ? policy.browserUrl(args.url) : null;
         record = args.browserId ? selectRecord(session, args.browserId) : create(session, "agent", args.newTab === true, args.incognito);
         if (args.incognito !== undefined && record.incognito !== (!ctx.isMate || args.incognito)) throw new Error("This tab has a different cookie mode. Open a new tab with the requested mode.");
-        if (url) await run(session, record, "agent", "action", { kind: "navigate", url: url }, args.intent);
+        if (url) await run(session, record, "agent", "action", { kind: "navigate", url: url }, args.intent, presentationStart);
+        else actionRevision = record.presentationRevision || 0;
         value = projection(record);
       } else if (args.action === "finish") {
         if (!record || !record.runtime) throw new Error("Open a browser first");
@@ -227,11 +232,23 @@ function attachSharedBrowser(ctx) {
         var image = value.image; delete value.image;
         return { content: [{ type: "text", text: JSON.stringify(value) }, { type: "image", mimeType: "image/jpeg", data: image }] };
       } else {
-        value = await run(session, record, "agent", "action", policy.validateAction(Object.assign({}, args, { kind: args.action })), args.intent);
+        value = await run(session, record, "agent", "action", policy.validateAction(Object.assign({}, args, { kind: args.action })), args.intent, presentationStart);
       }
+      if (observer && observer.present) {
+        observer.phase('completed');
+        try {
+          observer.guard();
+          var expectedRecord = record, expectedEpoch = record.epoch, expectedUrl = record.url;
+          if ((record.presentationRevision || 0) !== actionRevision || record.control !== 'agent') throw new Error('The browser changed after this action.');
+          var view = await run(session, record, 'agent', 'inspect', null, args.intent);
+          if (view && view.url && policy.visibleUrl(view.url) !== expectedUrl) throw new Error('The browser navigated after this action.');
+          if (!view || typeof view.image !== 'string' || !view.image) throw new Error('No exact browser frame was returned.');
+          observer.present({ type: 'shared_browser_frame', sessionId: session.localId, browserId: record.id, data: view.image, width: view.width, height: view.height }, 'browser', record.id, require('./clay-control-target-projection').digest(view.image), function () { requireAccess(session); if (records.get(expectedRecord.id) !== expectedRecord || !recordAllowed(expectedRecord) || expectedRecord.epoch !== expectedEpoch || expectedRecord.url !== expectedUrl || expectedRecord.control !== 'agent' || (expectedRecord.presentationRevision || 0) !== actionRevision || !expectedRecord.runtime) throw new Error('Browser target changed.'); }, function (message, onSent) { return ctx.sendToSession(session.localId, message, onSent); });
+        } catch (visibilityError) { observer.noVisibility(); }
+      } else if (observer) observer.finish({ status: 'completed' });
       if (value && value.url) value.browserLink = "browser:" + policy.visibleUrl(value.url);
       return { content: [{ type: "text", text: JSON.stringify(value) }] };
-    } catch (e) { return { isError: true, content: [{ type: "text", text: e.message }] }; }
+    } catch (e) { if (observer) { if (observer.unknown) observer.unknown(); else observer.finish({ outcome: "uncertain" }); } return { isError: true, content: [{ type: "text", text: e.message }] }; }
   }
   async function openLinkedPage(session, url, incognito) {
     var record = sessionRecords(session).find(function (tab) {

package/lib/project-studio-presentation.js

@@ -0,0 +1,58 @@
+var crypto = require('crypto');
+
+// Visibility receipts observe existing workbench effects; they dispatch no product action.
+function attachStudioPresentation(ctx) {
+  var pending = new Map();
+  function begin(session, action) {
+    var display = ctx.getPresentation && ctx.getPresentation(session);
+    if (!display) return null;
+    var source = display.source(), observer = display.track('studio', action);
+    if (!observer) return null;
+    var id = crypto.randomUUID(), token = crypto.randomUUID(), record;
+    function end(status, viewer) {
+      if (!record || !pending.has(id)) return;
+      pending.delete(id); clearTimeout(record.timer);
+      if (viewer) observer.focus(viewer);
+      observer.finish({ status: status });
+    }
+    function cancel() { if (record) { pending.delete(id); clearTimeout(record.timer); } observer.cancel(); }
+    return {
+      phase: observer.phase,
+      guard: observer.guard,
+      noVisibility: function () { observer.finish({ status: "render_unknown" }); },
+      fail: function () { cancel(); },
+      unknown: function () { observer.finish({ outcome: 'uncertain' }); },
+      present: function (message, surface, key, revision, validate, send) {
+        observer.guard();
+        if (pending.size >= 100) { observer.finish({ status: 'render_unknown' }); return 0; }
+        var target = { kind: 'surface', sourceSlug: source.sourceSlug, sourceSessionId: session.localId, sourceSessionOriginId: source.sourceSessionOriginId,
+          runtimeId: source.runtimeId, surface: surface, key: key, revision: revision };
+        observer.target(target, validate); observer.guard();
+        var evidence = Object.assign({ version: 1, id: id, activityId: observer.id, token: token, deadline: Date.now() + 5000, target: target }, source);
+        record = { session: session, source: source, evidence: evidence, observer: observer, viewers: new Set(), end: end, cancel: cancel };
+        pending.set(id, record);
+        record.timer = setTimeout(function () { end('render_unknown'); }, 5000); record.timer.unref();
+        var sent = send(Object.assign({}, message, { controlPresentation: evidence }), function (ws) { record.viewers.add(ws); });
+        if (sent > 0) { if (surface !== 'browser') observer.phase('delivered'); }
+        else end('render_unknown');
+        return sent;
+      }
+    };
+  }
+  function handleMessage(ws, msg) {
+    if (msg.type !== 'clay_studio_rendered') return false;
+    var record = pending.get(msg.id);
+    if (!record || record.evidence.token !== msg.token || !record.viewers.has(ws)) return true;
+    try {
+      record.observer.guard();
+      if (Date.now() > record.evidence.deadline) { record.end('render_unknown', ws); return true; }
+      if (ws.readyState !== 1 || ws._clayAuthCheck && !ws._clayAuthCheck() ||
+        ws._clayActiveSession !== record.session.localId || ctx.getSessionForWs(ws) !== record.session || (ws._clayUser && ws._clayUser.id || null) !== record.source.ownerId ||
+        msg.sessionOriginId !== record.source.sourceSessionOriginId || msg.revision !== record.evidence.target.revision) throw new Error('Studio viewer or target changed.');
+      record.end(msg.visible === true ? 'rendered' : 'render_unknown', ws);
+    } catch (error) { record.cancel(); }
+    return true;
+  }
+  return { begin: begin, handleMessage: handleMessage };
+}
+module.exports = { attachStudioPresentation: attachStudioPresentation };