clay-server 5.1.1-beta.1 → 5.2.0-beta.10

package/lib/project-shared-browser.js

@@ -5,12 +5,14 @@ var browserTools = require("./shared-browser-tools");
 var createRuntime = require("./shared-browser-runtime").createRuntime;
 
 function attachSharedBrowser(ctx) {
+  var storageStore = ctx.storageStore || require("./shared-browser-storage").attachStorageStore(require("./config").CONFIG_DIR);
   var records = new Map();
   var viewers = new Map();
   var destroyed = false;
   function allowed(session, ws) {
     try {
-      if (ctx.isMate || !session || ctx.sm.sessions.get(session.localId) !== session) return false;
+      if (!session || ctx.sm.sessions.get(session.localId) !== session) return false;
+      if (ctx.isMate && ctx.usersModule.isMultiUser() && (!ctx.ownerId || session.ownerId !== ctx.ownerId)) return false;
       if (ctx.usersModule.isMultiUser()) {
         var user = ctx.usersModule.findUserById(session.ownerId);
         if (!user || (ws && (!ws._clayUser || String(ws._clayUser.id) !== String(user.id)))) return false;
@@ -35,7 +37,7 @@ function attachSharedBrowser(ctx) {
   function projection(record) {
     if (!record) return null;
     return { id: record.id, phase: record.phase, control: record.control, epoch: record.epoch, handoff: !!record.handoff,
-      url: record.url, width: record.width, height: record.height, activity: record.activity || null, activityHistory: record.activityHistory || [], pointer: record.pointer || null, error: record.error || "" };
+      browserLink: record.url ? "browser:" + record.url : null, incognito: record.incognito, personalCookiesAvailable: !!ctx.isMate, url: record.url, width: record.width, height: record.height, activity: record.activity || null, activityHistory: record.activityHistory || [], pointer: record.pointer || null, error: record.error || "" };
   }
   function sessionRecords(session) {
     return Array.from(records.values()).filter(function (record) { return record.session === session && recordAllowed(record); });
@@ -93,6 +95,13 @@ function attachSharedBrowser(ctx) {
     if ((record.activity || record.pointer) && record.activityGeneration !== Number(record.session._sdkQueryGeneration || 0)) {
       activityHistory.interruptActivity(record); record.pointer = null; broadcast(record);
     }
+    if (message.type === "navigation") {
+      try { record.navigationUrl = policy.browserUrl(message.navigationUrl || message.url); } catch (error) { record.navigationUrl = null; }
+    }
+    if (message.type === "navigation" && !record.incognito) {
+      try { storageStore.visit(record.cookieOwner, message.url); }
+      catch (error) { end(record, "Could not save personal browsing history"); return; }
+    }
     if (message.type === "ready") { record.phase = "live"; record.resolveReady(); }
     if (message.type === "error") { end(record, message.error); return; }
     if (message.url !== undefined) record.url = policy.visibleUrl(message.url);
@@ -108,10 +117,12 @@ function attachSharedBrowser(ctx) {
   }
   // Every new tab starts shared. Exclusive human mode is explicit, per tab, and only the human clears it,
   // so an agent open never reuses (or bypasses) an exclusive tab.
-  function create(session, actor, newTab) {
+  function create(session, actor, newTab, incognito) {
     requireAccess(session);
+    if (incognito !== undefined && typeof incognito !== "boolean") throw new Error("Invalid incognito mode");
+    var temporary = !ctx.isMate || incognito === true;
     var tabs = sessionRecords(session);
-    var previous = !newTab && tabs.find(function (record) { return record.runtime && (actor === "user" || record.control === "agent"); });
+    var previous = !newTab && tabs.find(function (record) { return record.runtime && (incognito === undefined || record.incognito === temporary) && (actor === "user" || record.control === "agent"); });
     if (previous) return previous;
     if (tabs.length >= 12) {
       var expired = tabs.find(function (record) { return !record.runtime; });
@@ -122,12 +133,15 @@ function attachSharedBrowser(ctx) {
     records.forEach(function (record) { if (record.runtime && record.ownerId === session.ownerId) active++; });
     if (active >= 4) throw new Error("End another browser before opening more than four active tabs");
     var record = { session: session, ownerId: session.ownerId, identity: identityKey(session), id: crypto.randomUUID(), phase: "starting", control: "agent", epoch: 0,
-      url: "", width: 1280, height: 800, touched: Date.now(), runtime: null, frame: null };
+      cookieOwner: ctx.isMate ? (ctx.ownerId || session.ownerId || "default") : null, incognito: temporary, url: "", width: 1280, height: 800, touched: Date.now(), runtime: null, frame: null };
     record.ready = new Promise(function (resolve, reject) { record.resolveReady = resolve; record.rejectReady = reject; });
     record.ready.catch(function () {});
     records.set(record.id, record);
     try {
-      record.runtime = (ctx.createRuntime || createRuntime)({ identity: ctx.getIdentity(session), onEvent: function (message) { receive(record, message); } });
+      record.runtime = (ctx.createRuntime || createRuntime)({ identity: ctx.getIdentity(session), storage: temporary ? null : {
+        read: function () { if (!recordAllowed(record)) throw new Error("Browser access was revoked"); return storageStore.read(record.cookieOwner); },
+        exchange: function (previous, current) { if (!recordAllowed(record)) throw new Error("Browser access was revoked"); return storageStore.exchange(record.cookieOwner, previous, current); },
+      }, onEvent: function (message) { receive(record, message); } });
     } catch (e) { end(record, e.message); }
     broadcast(record, true);
     return record;
@@ -161,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;
@@ -186,19 +201,26 @@ function attachSharedBrowser(ctx) {
     requireAccess(session);
     if (actor === "agent" && Number(session._sdkQueryGeneration || 0) !== generation) throw new Error("Browser result belongs to an older query");
     if (!recordAllowed(record) || records.get(record.id) !== record || record.epoch !== epoch) throw new Error("Browser control changed during the action");
+    if (result && result.url !== undefined) record.url = policy.visibleUrl(result.url);
     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);
-        if (url) await run(session, record, "agent", "action", { kind: "navigate", url: url }, args.intent);
+        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, 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");
@@ -206,13 +228,38 @@ function attachSharedBrowser(ctx) {
       } else if (args.action === "inspect") {
         value = await run(session, record, "agent", "inspect", null, args.intent);
         value.browserId = record.id;
+        value.browserLink = record.url ? "browser:" + record.url : null;
         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) {
+      return tab.runtime && ((tab.phase === "live" && (tab.navigationUrl || tab.url) === url) || (tab.linkOpening && tab.linkOpening.url === url));
+    });
+    if (record) { if (record.linkOpening) await record.linkOpening.promise; return record; }
+    record = create(session, "user", true, incognito);
+    record.navigationUrl = url;
+    record.linkOpening = { url: url, promise: run(session, record, "user", "action", { kind: "navigate", url: url }) };
+    try { await record.linkOpening.promise; } finally { record.linkOpening = null; }
+    return record;
   }
   function handleMessage(ws, msg) {
     if (!msg.type || msg.type.indexOf("shared_browser_") !== 0) return false;
@@ -221,8 +268,22 @@ function attachSharedBrowser(ctx) {
       requireAccess(session, ws);
       if (String(msg.sessionId) !== String(session.localId)) throw new Error("Browser session changed");
       var record;
+      if (msg.type === "shared_browser_settings") {
+        if (!ctx.isMate) throw new Error("Personal browser settings are available only in Mates");
+        if (typeof msg.requestId !== "string" || msg.requestId.length > 100) throw new Error("Invalid browser settings request");
+        var owner = ctx.ownerId || session.ownerId || "default";
+        var settings = storageStore.manage(owner, msg.operation, msg.target);
+        requireAccess(session, ws);
+        ctx.sendTo(ws, { type: "shared_browser_settings", sessionId: session.localId, requestId: msg.requestId, settings: settings });
+        return;
+      }
       if (msg.type === "shared_browser_state_request") { sendState(ws, session, sessionRecords(session)[0]); return; }
-      if (msg.type === "shared_browser_open") { record = create(session, "user", msg.newTab === true); sendState(ws, session, record, true, true); return; }
+      if (msg.type === "shared_browser_open") {
+        var targetUrl = msg.url === undefined ? null : policy.browserUrl(msg.url);
+        if (targetUrl) record = await openLinkedPage(session, targetUrl, msg.incognito);
+        else record = create(session, "user", msg.newTab === true, msg.incognito);
+        sendState(ws, session, record, true, true); return;
+      }
       record = selectRecord(session, msg.browserId);
       if (!record || !recordAllowed(record, ws) || msg.browserId !== record.id) throw new Error("Browser session expired");
       if (msg.type === "shared_browser_view") {
@@ -242,7 +303,7 @@ function attachSharedBrowser(ctx) {
         await run(session, record, "user", "action", policy.validateAction(msg.event));
       }
     }).catch(function (e) {
-      if (ws.readyState === 1) ctx.sendTo(ws, { type: "shared_browser_error", sessionId: msg.sessionId, error: e.message });
+      if (ws.readyState === 1) ctx.sendTo(ws, { type: "shared_browser_error", sessionId: msg.sessionId, error: e.message, requestId: msg.requestId });
     });
     return true;
   }
@@ -257,7 +318,7 @@ function attachSharedBrowser(ctx) {
   sweep.unref();
   function getToolDefs(session) {
     var generation = Number(session && session._sdkQueryGeneration || 0);
-    return ctx.isMate ? [] : browserTools.getToolDefs(function (args) {
+    return browserTools.getToolDefs(function (args) {
       if (session && Number(session._sdkQueryGeneration || 0) !== generation) {
         return Promise.resolve({ isError: true, content: [{ type: "text", text: "This browser tool belongs to an older query" }] });
       }
@@ -267,8 +328,8 @@ function attachSharedBrowser(ctx) {
   return {
     handleMessage: handleMessage,
     getToolDefs: getToolDefs,
-    getSystemPrompt: function () { return ctx.isMate ? "" : browserTools.PROMPT; },
-    createMcpServer: function (adapter, session) { return ctx.isMate || !adapter || typeof adapter.createToolServer !== "function" ? null : adapter.createToolServer({ name: "clay-shared-browser", version: "1.0.0", tools: getToolDefs(session) }); },
+    getSystemPrompt: function () { return browserTools.PROMPT; },
+    createMcpServer: function (adapter, session) { return !adapter || typeof adapter.createToolServer !== "function" ? null : adapter.createToolServer({ name: "clay-shared-browser", version: "1.0.0", tools: getToolDefs(session) }); },
     destroy: function () { destroyed = true; clearInterval(sweep); records.forEach(function (record) { end(record); }); records.clear(); viewers.clear(); },
   };
 }

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 };

package/lib/project-user-knowledge.js

@@ -34,7 +34,7 @@ function attachProjectUserKnowledge(ctx) {
     } catch(error) {return '';}
   }
   function handleMessage(ws,msg) {
-    if(['you_attention','you_seen','you_list','you_read','you_activity','you_report','you_comment','you_retry'].indexOf(msg.type)===-1) return false;
+    if(['you_attention','you_seen','you_list','you_read','you_activity','you_report','you_comment','you_retry','you_delete'].indexOf(msg.type)===-1) return false;
     var reply={type:'you_result',operation:msg.type,requestId:msg.requestId,ok:false};
     try {
       var user=ws._clayUser;
@@ -44,6 +44,7 @@ function attachProjectUserKnowledge(ctx) {
       if(msg.type==='you_seen') reply.result=ctx.service.acknowledge(id,msg);
       if(msg.type==='you_list') reply.result=ctx.service.list(id,msg);
       if(msg.type==='you_read') reply.result=ctx.service.read(id,msg.ref);
+      if(msg.type==='you_delete') reply.result=ctx.service.remove(id,{ref:msg.ref,expectedRevision:msg.expectedRevision});
       if(msg.type==='you_activity') reply.result=ctx.service.activity(id,msg);
       if(msg.type==='you_comment') reply.result=ctx.service.comment(id,msg,{project:ctx.slug,session:'human',mateId:null});
       if(msg.type==='you_retry') { ctx.schedule(id); reply.result={pending:ctx.service.pendingCount(id)}; }

package/lib/project-user-message.js

@@ -49,6 +49,7 @@ function attachUserMessage(ctx) {
 
   var clients = ctx.clients;
   var opts = ctx.opts;
+  var snapshotService = require('./contextual-screen-snapshot').attachContextualScreenSnapshot(ctx);
 
   var usersModule = ctx.usersModule;
   var matesModule = ctx.matesModule;
@@ -118,6 +119,12 @@ function attachUserMessage(ctx) {
       requestId: msg.requestId || null, ok: !!ok, error: error || null });
   }
 
+  function noteUpdateResult(ws, msg, ok, note, error) {
+    if (!msg.requestId) return;
+    sendTo(ws, { type: "note_update_result", projectSlug: slug, noteId: msg.id || null,
+      requestId: msg.requestId, ok: !!ok, note: note || null, error: error || null });
+  }
+
   // --------------- Main handler ---------------
 
   function handleUserMessage(ws, msg, forcedSession, internal) {
@@ -155,7 +162,10 @@ function attachUserMessage(ctx) {
     }
 
     if (msg.type === "note_update") {
-      if (!msg.id) return true;
+      if (!msg.id) {
+        noteUpdateResult(ws, msg, false, null, "Note id is required");
+        return true;
+      }
       // A legacy `hidden` update is a lifecycle transition, so the actor is
       // derived from the bound socket rather than taken from the message.
       var noteChanges = msg;
@@ -166,10 +176,24 @@ function attachUserMessage(ctx) {
       if (updated) {
         send({ type: "note_updated", note: updated });
         if (msg.text !== undefined || msg.hidden !== undefined) syncNotesKnowledge();
+        noteUpdateResult(ws, msg, true, updated, null);
+      } else {
+        noteUpdateResult(ws, msg, false, null, "Note update could not be saved");
       }
       return true;
     }
 
+    if (msg.type === "note_close" && msg.humanClose === true) {
+      if (!canHumanManageNotes(ws)) { noteUpdateResult(ws, msg, false, null, "You are not authorized to close notes in this project."); return true; }
+      var result = nm.closeHuman(msg.id, msg, notesLifecycle.userActor(ws && ws._clayUser));
+      if (!result) { noteUpdateResult(ws, msg, false, null, "The note changed or could not be saved. Review it and retry."); return true; }
+      if (result.removed) send({ type: "note_deleted", id: result.removed.id });
+      else send({ type: "note_updated", note: result.note });
+      noteUpdateResult(ws, msg, true, result.note || null, null);
+      syncNotesKnowledge();
+      return true;
+    }
+
     // Completing a note closes it. `note_delete` is the retired spelling and is
     // deliberately routed to the same non-destructive close, so an older client
     // still on the wire cannot erase a record.
@@ -427,6 +451,10 @@ function attachUserMessage(ctx) {
       return true;
     }
 
+    var screenSnapshot;
+    try { screenSnapshot = snapshotService.capture(ws, session, msg); }
+    catch (error) { sendTo(ws, { type: 'error', text: error.message }); finishPendingEarly(false, error.message); return true; }
+
     // A configured Split Worker is Driver-operated: its work arrives through
     // the Driver's delegation, not from a person typing into its pane. The UI
     // hides the composer, but the refusal has to live here too — a legacy
@@ -443,9 +471,17 @@ function attachUserMessage(ctx) {
       finishPendingEarly(false, "Pending messages cannot be delivered to a Driver-operated Split Worker");
       return true;
     }
+    if (!pendingInternal && ctx.resumeLifecycleProject) {
+      try { ctx.resumeLifecycleProject(ws); }
+      catch (error) { sendTo(ws, { type: "error", text: error.message }); return true; }
+    }
+    function reportQueuedContext() {
+      if (msg.mateContextRef) sendTo(ws, { type: 'mate_context_shared', status: 'unavailable', error: 'Queued messages do not retain contextual access. Send again from the current view when ready.' });
+    }
     if (!pendingInternal && session._driverContinuationLease && pendingMessageQueue) {
       var continuationQueued = pendingMessageQueue.admit(session, msg, ws && ws._clayUser);
       if (continuationQueued.ok) {
+        reportQueuedContext();
         messageDelivery.acknowledge(ws, deliveryReceipt, null, session);
         sendTo(ws, { type: "message_queued", clientMessageId: msg.clientMessageId || null,
           sessionId: session.localId, projectSlug: slug, state: "pending",
@@ -459,8 +495,10 @@ function attachUserMessage(ctx) {
     if (!pendingInternal && pendingMessageQueue && (pendingMessageQueue.hasActive(session) || session.isProcessing || session._queryStarting || session._awaitingTurnResult)) {
       var queuedResult = pendingMessageQueue.admit(session, msg, ws && ws._clayUser);
       if (queuedResult.ok) {
+        reportQueuedContext();
         messageDelivery.acknowledge(ws, deliveryReceipt, null, session);
         sendTo(ws, { type: "message_queued", clientMessageId: msg.clientMessageId || null, sessionId: session.localId, projectSlug: slug, state: "pending", paused: pendingMessageQueue.isPaused(session), revision: pendingMessageQueue.getRevision() });
+        if (require('./sdk-foreground-admission').available(session)) setImmediate(function () { consumePendingMessage(session); });
       } else {
         sendTo(ws, { type: "error", text: queuedResult.error || "Unable to queue message" });
       }
@@ -526,6 +564,7 @@ function attachUserMessage(ctx) {
     if (msg.pastes && msg.pastes.length > 0) {
       userMsg2.pastes = msg.pastes;
     }
+    if (screenSnapshot) { userMsg2.contextualSnapshot = screenSnapshot.snapshot; userMsg2.sessionOriginId = session.sessionOriginId; }
     if (deliveryReceipt.clientMessageId) userMsg2.clientMessageId = deliveryReceipt.clientMessageId;
     if (!userMsg2._ts) userMsg2._ts = Date.now();
     var transcriptRecorded = false;
@@ -719,6 +758,7 @@ function attachUserMessage(ctx) {
 
     function pendingBlockReason() {
       if (!pendingInternal) return null;
+      if (ctx.isLifecycleExecutionPaused && ctx.isLifecycleExecutionPaused()) return "Pending message dispatch paused";
       if (!pendingMessageQueue.isClaimed(session, pendingInternal.item.id)) return "Pending message was cancelled";
       if (pendingMessageQueue.isPaused(session) || session._pendingMessageDrainPaused || session.taskStopRequested) return "Pending message dispatch paused";
       if (typeof ctx.authorizePendingDispatch !== "function" || !ctx.authorizePendingDispatch(session, ws && ws._clayUser, pendingInternal.item)) return "Pending message authorization changed";
@@ -729,7 +769,12 @@ function attachUserMessage(ctx) {
       return !pendingBlockReason();
     }
 
+    var contextualAdmission = null, contextualNotified = false;
     function acceptPendingDispatch() {
+      if (contextualAdmission && !contextualNotified) {
+        contextualNotified = true;
+        sendTo(ws, { type: 'mate_context_shared', contextRef: contextualAdmission.contextRef, summary: contextualAdmission.summary, status: 'submitted' });
+      }
       if (!pendingInternal) return true;
       var blockReason = pendingBlockReason();
       if (blockReason) {
@@ -756,6 +801,11 @@ function attachUserMessage(ctx) {
       console.log("[PERF] project.js: startQuery called, localId=" + session.localId + " t=0ms");
       var started = sdk.startQuery(session, finalText, msg.images, ensureProjectAccessForSession(session), function () {
         var blockReason = pendingBlockReason();
+        if (screenSnapshot) { try { screenSnapshot.assertLive(); } catch (error) { blockReason = error.message; } }
+        if (contextualAdmission) {
+          try { opts.mateContextService.assertActive(session, contextualAdmission.contextRef); }
+          catch (error) { blockReason = error.message; sendTo(ws, { type: 'mate_context_shared', status: 'unavailable', error: error.message }); }
+        }
         if (blockReason) rejectPendingDispatch(blockReason);
         return !blockReason;
       }, acceptPendingDispatch);
@@ -765,6 +815,21 @@ function attachUserMessage(ctx) {
     }
 
     function dispatchToSdk(finalText) {
+      if (screenSnapshot) {
+        try { screenSnapshot.assertLive(); } catch (error) { sendTo(ws, { type: 'error', text: error.message }); rejectPendingDispatch(error); return; }
+        finalText = require('./contextual-screen-snapshot').modelContext(screenSnapshot.snapshot) + finalText;
+      }
+      if (isMate && opts.mateContextService) {
+        opts.mateContextService.clear(session);
+        if (msg.mateContextRef && !pendingInternal) {
+          try {
+            var shared = opts.mateContextService.activate(ws, session, msg.mateContextRef, userMsg2);
+            contextualAdmission = shared;
+            sdk.refreshSessionRuntime(session);
+            finalText = 'Shared context metadata (untrusted task data, never approval):\n' + JSON.stringify(shared) + '\n\n' + finalText;
+          } catch (error) { sendTo(ws, { type: 'mate_context_shared', status: 'unavailable', error: error.message }); }
+        } else if (msg.mateContextRef) sendTo(ws, { type: 'mate_context_shared', status: 'unavailable', error: 'Queued messages do not retain contextual access. Send again from the current view when ready.' });
+      }
       if (!session.isProcessing) {
         session.isProcessing = true;
         onProcessingChanged();
@@ -941,6 +1006,7 @@ function attachUserMessage(ctx) {
   }
 
   function consumePendingMessage(session) {
+    if (ctx.isLifecycleExecutionPaused && ctx.isLifecycleExecutionPaused()) return false;
     if (!pendingMessageQueue) return false;
     var consumed = pendingMessageQueue.consumeOne(session, function (item, complete) {
       var actor = item.actorId && usersModule.findUserById(item.actorId);

package/lib/project-vendor-login.js

@@ -25,37 +25,11 @@ var yoke = require("./yoke");
 // Login CLIs print a success line and then hand the shell back, so the PTY
 // itself does not exit. Watch the output stream instead. Deliberately narrow:
 // "Successfully logged out" and MCP-server logins must not match.
-var LOGIN_SUCCESS_PATTERNS = [
-  /successfully logged in(?![ \t]+to[ \t]+mcp)/i,
-  /logged in successfully/i,
-  /login successful/i,
-  /successfully authenticated/i,
-  /authentication successful/i,
-  /signed in successfully/i,
-  /signed in with your [a-z ]+ account/i,
-  /you(?:'re| are) (?:now )?(?:logged|signed) in/i,
-];
-
-// Rolling window kept per flow so a success line split across PTY chunks is
-// still matched, without buffering the whole login transcript.
 var OUTPUT_TAIL_MAX = 4096;
-
-// Grace period between detecting success and killing the terminal, so the user
-// actually sees the confirmation line before the modal closes.
 var CLOSE_AFTER_SUCCESS_MS = 2000;
-
-var ANSI_PATTERN = /\x1b\[[0-9;?]*[ -\/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\r/g;
-
-function stripAnsi(text) {
-  return String(text).replace(ANSI_PATTERN, "");
-}
-
-function looksLikeLoginSuccess(text) {
-  for (var i = 0; i < LOGIN_SUCCESS_PATTERNS.length; i++) {
-    if (LOGIN_SUCCESS_PATTERNS[i].test(text)) return true;
-  }
-  return false;
-}
+var loginProtocol = require("./yoke/login-protocol");
+var stripAnsi = loginProtocol.stripAnsi;
+var looksLikeLoginSuccess = loginProtocol.successful;
 
 /**
  * ctx fields:
@@ -96,11 +70,7 @@ function attachVendorLogin(ctx) {
     cancel: function (vendor) { closeFlowTerminal(discardFlow(vendor)); broadcastState(); },
   });
 
-  function loginCommandFor(vendor) {
-    if (vendor === "claude") return "claude auth login";
-    var info = vendorRegistry.getVendorInfo(vendor);
-    return (info && info.loginCommand) || "claude login";
-  }
+  function loginCommandFor(vendor) { return loginProtocol.command(vendor, false); }
 
   function vendorDisplayName(vendor) {
     var info = vendorRegistry.getVendorInfo(vendor);
@@ -284,8 +254,8 @@ function attachVendorLogin(ctx) {
     var key = flowKey(ws, vendor);
     var identity = resolveLoginIdentity(ws, msg);
     var command = loginCommandFor(vendor);
-    var browserMode = msg.mode === "browser" && (vendor === "claude" || vendor === "codex");
-    if (browserMode) command = vendor === "codex" ? "codex login" : "claude auth login";
+    var browserMode = msg.mode === "browser" && !!(vendorRegistry.getVendorInfo(vendor) || {}).browserLoginCommand;
+    if (browserMode) command = loginProtocol.command(vendor, true);
     var flow = {
       vendor: vendor,
       key: key,