clay-server 3.8.1 → 4.0.0-beta.2

package/lib/users-home-surface-preferences.js

@@ -0,0 +1,99 @@
+// Per-user persistence for durable Home conversation selections.
+
+function attachHomeSurfacePreferences(deps) {
+  var loadUsers = deps.loadUsers;
+  var saveUsers = deps.saveUsers;
+
+  function defaults() {
+    return { surface: null, projectSlug: null, activeMateId: null, activeSessionByMate: {}, sidebarCollapsed: false, chatScope: "all", subSurface: "chat" };
+  }
+
+  function validId(value) {
+    return typeof value === "string" && /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(value);
+  }
+
+  function validSessionReference(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= 256 && !/[\x00-\x1f]/.test(value);
+  }
+
+  function validProjectSlug(value) {
+    return typeof value === "string" && /^[a-z0-9][a-z0-9_-]{0,127}$/.test(value);
+  }
+
+  function normalize(value) {
+    var source = value && typeof value === "object" ? value : {};
+    var sessions = source.activeSessionByMate && typeof source.activeSessionByMate === "object" && !Array.isArray(source.activeSessionByMate)
+      ? source.activeSessionByMate
+      : {};
+    var normalizedSessions = {};
+    var mateIds = Object.keys(sessions);
+    for (var i = 0; i < mateIds.length; i++) {
+      if (!validId(mateIds[i]) || !validSessionReference(sessions[mateIds[i]])) continue;
+      normalizedSessions[mateIds[i]] = sessions[mateIds[i]];
+    }
+    return {
+      surface: source.surface === "home" || source.surface === "project" ? source.surface : null,
+      projectSlug: validProjectSlug(source.projectSlug) ? source.projectSlug : null,
+      activeMateId: validId(source.activeMateId) ? source.activeMateId : null,
+      activeSessionByMate: normalizedSessions,
+      sidebarCollapsed: source.sidebarCollapsed === true,
+      chatScope: source.chatScope === "current" ? "current" : "all",
+      subSurface: source.subSurface === "debates" ? "debates" : "chat",
+    };
+  }
+
+  function loadSingleUserPreference() {
+    try {
+      var config = require("./config");
+      var current = config.loadConfig() || {};
+      return normalize(current.homeSurfacePreference);
+    } catch (e) {
+      return defaults();
+    }
+  }
+
+  function saveSingleUserPreference(preference) {
+    try {
+      var config = require("./config");
+      var current = config.loadConfig() || {};
+      config.saveConfig(Object.assign({}, current, { homeSurfacePreference: preference }));
+      return { ok: true, preference: preference };
+    } catch (e) {
+      return { error: "Unable to save Home surface preference" };
+    }
+  }
+
+  function getHomeSurfacePreference(userId) {
+    var data = loadUsers();
+    for (var i = 0; i < data.users.length; i++) {
+      if (data.users[i].id === userId) return normalize(data.users[i].homeSurfacePreference);
+    }
+    if (userId === "default") return loadSingleUserPreference();
+    return defaults();
+  }
+
+  function setHomeSurfacePreference(userId, patch) {
+    var current = getHomeSurfacePreference(userId);
+    var merged = Object.assign({}, current, patch || {});
+    if (patch && patch.activeSessionByMate && typeof patch.activeSessionByMate === "object") {
+      merged.activeSessionByMate = Object.assign({}, current.activeSessionByMate, patch.activeSessionByMate);
+    }
+    var next = normalize(merged);
+    var data = loadUsers();
+    for (var i = 0; i < data.users.length; i++) {
+      if (data.users[i].id !== userId) continue;
+      data.users[i].homeSurfacePreference = next;
+      saveUsers(data);
+      return { ok: true, preference: next };
+    }
+    if (userId === "default") return saveSingleUserPreference(next);
+    return { error: "User not found" };
+  }
+
+  return {
+    getHomeSurfacePreference: getHomeSurfacePreference,
+    setHomeSurfacePreference: setHomeSurfacePreference,
+  };
+}
+
+module.exports = { attachHomeSurfacePreferences: attachHomeSurfacePreferences };

package/lib/users-preferences.js

@@ -334,14 +334,11 @@ function attachPreferences(deps) {
     return { error: "User not found" };
   }
 
-  // --- Per-user Mates UI toggle ---
+  // --- Per-user project Mate DM shortcut toggle ---
   //
-  // When disabled, the entire Mates surface (sidebar avatars, DM "Create a
-  // Mate" entry, home-hub mates strip) is hidden for this user; multi-user
-  // and the rest of the sidebar are unaffected. Default is OFF: Mates is
-  // opt-in, not opt-out. Stored as `matesEnabled`; only the literal `true`
-  // enables it, so brand-new users (no field set) get the default-off
-  // experience and must turn Mates on explicitly in settings.
+  // `matesEnabled` is retained as the persisted field for compatibility.
+  // It now controls only project-local Mate DM shortcuts. The broader Mate
+  // capability surface is always available. Default remains off.
 
   function getMatesEnabled(userId) {
     var data = loadUsers();

package/lib/users.js

@@ -6,6 +6,8 @@ var { CONFIG_DIR } = require("./config");
 var { attachAuth } = require("./users-auth");
 var { DEFAULT_PERMISSIONS, ALL_PERMISSIONS, attachPermissions } = require("./users-permissions");
 var { attachPreferences } = require("./users-preferences");
+var { attachHomeDockPreferences } = require("./users-home-dock-preferences");
+var { attachHomeSurfacePreferences } = require("./users-home-surface-preferences");
 
 var USERS_FILE = path.join(CONFIG_DIR, "users.json");
 
@@ -394,6 +396,8 @@ function removeExpiredInvites() {
 var auth = attachAuth({ loadUsers: loadUsers, saveUsers: saveUsers, findAdmin: findAdmin });
 var permissions = attachPermissions({ loadUsers: loadUsers, saveUsers: saveUsers, findUserById: findUserById });
 var preferences = attachPreferences({ loadUsers: loadUsers, saveUsers: saveUsers });
+var homeDockPreferences = attachHomeDockPreferences({ loadUsers: loadUsers, saveUsers: saveUsers });
+var homeSurfacePreferences = attachHomeSurfacePreferences({ loadUsers: loadUsers, saveUsers: saveUsers });
 
 // Alias auth functions
 var isMultiUser = auth.isMultiUser;
@@ -442,6 +446,10 @@ var markWhatsNewSeen = preferences.markWhatsNewSeen;
 var getTerminalFont = preferences.getTerminalFont;
 var setTerminalFont = preferences.setTerminalFont;
 var setMateOnboarded = preferences.setMateOnboarded;
+var getHomeDockPreference = homeDockPreferences.getHomeDockPreference;
+var setHomeDockPreference = homeDockPreferences.setHomeDockPreference;
+var getHomeSurfacePreference = homeSurfacePreferences.getHomeSurfacePreference;
+var setHomeSurfacePreference = homeSurfacePreferences.setHomeSurfacePreference;
 
 module.exports = {
   USERS_FILE: USERS_FILE,
@@ -511,6 +519,10 @@ module.exports = {
   markWhatsNewSeen: markWhatsNewSeen,
   getTerminalFont: getTerminalFont,
   setTerminalFont: setTerminalFont,
+  getHomeDockPreference: getHomeDockPreference,
+  setHomeDockPreference: setHomeDockPreference,
+  getHomeSurfacePreference: getHomeSurfacePreference,
+  setHomeSurfacePreference: setHomeSurfacePreference,
   getDeletedBuiltinKeys: getDeletedBuiltinKeys,
   addDeletedBuiltinKey: addDeletedBuiltinKey,
   removeDeletedBuiltinKey: removeDeletedBuiltinKey,

package/lib/whats-new-content.js

@@ -70,13 +70,13 @@ var ENTRIES = [
     title: "GUI is back as the default",
     publishedAt: "2026-07-01",
     image: null,
-    summary: "Anthropic reversed the June 15 billing split, so SDK usage is no longer billed separately. Clay opens Claude sessions in the GUI chat again by default. Mates is now off by default as it winds down.",
+    summary: "Anthropic reversed the June 15 billing split, so SDK usage is no longer billed separately. Clay opens Claude sessions in the GUI chat again by default. Project Mate DM shortcuts are hidden by default.",
     body: '' +
       '<p><strong>Good news: Anthropic walked back the June 15 billing change.</strong> The planned Interactive vs. Programmatic split (which would have charged Claude Agent SDK usage at full API rates) is off the table, so the reason we moved everyone to the TUI is gone.</p>' +
       '<h3>GUI is the default again</h3>' +
       '<p>New Claude sessions open in the <strong>GUI chat</strong> (SDK) by default, the way they did before. The embedded <code>claude</code> <strong>TUI</strong> is still there whenever you want it &mdash; toggle <strong>"Open Claude as terminal (TUI)"</strong> in Settings.</p>' +
-      '<h3>Mates is off by default</h3>' +
-      '<p>As announced, <strong>Mates</strong> is no longer a first-class Clay feature. It is now <strong>off by default</strong> so Clay stays focused as a developer tool. Your existing Mates and their knowledge files remain on disk &mdash; if you still use them, re-enable Mates in <strong>Settings</strong>.</p>' +
+      '<h3>Project Mate DM shortcuts are optional</h3>' +
+      '<p>Mate DM shortcuts inside project workspaces are hidden by default and can be shown in <strong>Settings</strong>. Mates themselves remain available in Clay Home, together with their conversations, memory, debates, and project collaboration.</p>' +
       '<p>Clay only gets sharper from here.</p>',
   },
 ];

package/lib/workspace-assignment-service.js

@@ -0,0 +1,420 @@
+var fs = require("fs");
+var path = require("path");
+var crypto = require("crypto");
+
+var ACTIVE = { proposed: true, starting: true, running: true };
+var MAX_RUNNING = 3;
+
+function clean(value, max) {
+  if (typeof value !== "string") return "";
+  return value.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim().slice(0, max);
+}
+
+function userStorageKey(userId) {
+  return crypto.createHash("sha256").update(String(userId || "_single_user")).digest("hex").slice(0, 24) + ".json";
+}
+
+function attachWorkspaceAssignmentService(ctx) {
+  var storageDir = ctx.storageDir || null;
+  var records = [];
+  var unsubscribers = {};
+  var pendingRestartReplay = {};
+
+  function recordFile(userId) {
+    return storageDir ? path.join(storageDir, userStorageKey(userId)) : null;
+  }
+
+  function saveUser(userId) {
+    var file = recordFile(userId);
+    if (!file) return;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    var owned = records.filter(function (record) { return record.userId === (userId || null); });
+    var temp = file + ".tmp." + process.pid;
+    fs.writeFileSync(temp, JSON.stringify(owned, null, 2), { mode: 0o600 });
+    fs.renameSync(temp, file);
+  }
+
+  function load() {
+    if (!storageDir) return;
+    var files = [];
+    try { files = fs.readdirSync(storageDir); } catch (e) { return; }
+    for (var i = 0; i < files.length; i++) {
+      if (!files[i].endsWith(".json") || files[i].indexOf(".tmp.") !== -1) continue;
+      try {
+        var loaded = JSON.parse(fs.readFileSync(path.join(storageDir, files[i]), "utf8"));
+        if (Array.isArray(loaded)) records = records.concat(loaded);
+      } catch (e) {}
+    }
+    var changedUsers = {};
+    for (var j = 0; j < records.length; j++) {
+      if (records[j].status !== "starting" && records[j].status !== "running") continue;
+      records[j].status = "interrupted";
+      records[j].error = "Clay restarted before this assignment completed.";
+      records[j].updatedAt = Date.now();
+      pendingRestartReplay[records[j].assignmentId] = true;
+      changedUsers[String(records[j].userId || "_single_user")] = records[j].userId || null;
+    }
+    var keys = Object.keys(changedUsers);
+    for (var k = 0; k < keys.length; k++) saveUser(changedUsers[keys[k]]);
+  }
+
+  function sourceKey(principal) {
+    return String(principal.userId || "_single_user") + ":" + principal.sourceProjectSlug + ":" + principal.sourceSessionRef;
+  }
+
+  function normalizePrincipal(principal) {
+    if (!principal || !principal.sourceProjectSlug) return null;
+    var project = ctx.getProjects().get(principal.sourceProjectSlug);
+    var manager = project && project.getSessionManager ? project.getSessionManager() : null;
+    var session = manager && manager.sessions ? manager.sessions.get(principal.sourceSessionId) : null;
+    if (!session && manager && manager.sessions && principal.sourceSessionRef) {
+      manager.sessions.forEach(function (candidate) {
+        if (!session && ctx.sessionRef(principal.sourceProjectSlug, candidate) === principal.sourceSessionRef) session = candidate;
+      });
+    }
+    if (!session) return null;
+    return Object.assign({}, principal, {
+      sourceSessionId: session.localId,
+      sourceSessionRef: ctx.sessionRef(principal.sourceProjectSlug, session),
+    });
+  }
+
+  function publicRecord(record) {
+    return {
+      assignmentId: record.assignmentId,
+      delivery: record.delivery || "new_session",
+      projectSlug: record.targetProjectSlug,
+      projectTitle: record.targetProjectTitle,
+      title: record.title,
+      task: record.task,
+      status: record.status,
+      sourceProjectSlug: record.sourceProjectSlug,
+      sourceSessionRef: record.sourceSessionRef,
+      targetSessionRef: record.targetSessionRef || null,
+      targetSessionTitle: record.targetSessionTitle || null,
+      resultSummary: record.resultSummary || "",
+      error: record.error || "",
+      createdAt: record.createdAt,
+      updatedAt: record.updatedAt,
+    };
+  }
+
+  function ownsProject(record, status) {
+    if (!status || status.isWorktree || status.isMate) return false;
+    if (ctx.isMultiUser()) return !!record.userId && status.projectOwnerId === record.userId;
+    return !status.projectOwnerId || (!!record.singleUserOwnerId && status.projectOwnerId === record.singleUserOwnerId);
+  }
+
+  function exactTarget(record) {
+    var project = ctx.getProjects().get(record.targetProjectSlug);
+    if (!project || !ownsProject(record, project.getStatus())) return null;
+    return project;
+  }
+
+  function exactSource(record) {
+    var project = ctx.getProjects().get(record.sourceProjectSlug);
+    if (!project) return null;
+    var status = project.getStatus();
+    if (!status || status.isMate !== true || status.mateId !== record.sourceMateId) return null;
+    if (ctx.isMultiUser() && status.projectOwnerId !== record.userId) return null;
+    var manager = project.getSessionManager();
+    var session = null;
+    if (manager && manager.sessions) {
+      manager.sessions.forEach(function (candidate) {
+        if (!session && ctx.sessionRef(record.sourceProjectSlug, candidate) === record.sourceSessionRef) session = candidate;
+      });
+    }
+    if (!session) return null;
+    if (ctx.isMultiUser() && session.ownerId !== record.userId) return null;
+    if (!ctx.isMultiUser() && session.ownerId && session.ownerId !== record.singleUserOwnerId) return null;
+    return { project: project, manager: manager, session: session };
+  }
+
+  function emit(record, eventType) {
+    var source = exactSource(record);
+    if (!source) return;
+    source.manager.sendAndRecord(source.session, {
+      type: eventType || "project_assignment_status",
+      assignment: publicRecord(record),
+      requestId: record.sourceRequestId || null,
+    });
+  }
+
+  function reconcileProject(projectSlug) {
+    for (var i = 0; i < records.length; i++) {
+      if (!pendingRestartReplay[records[i].assignmentId] || records[i].sourceProjectSlug !== projectSlug) continue;
+      if (!exactSource(records[i])) continue;
+      emit(records[i]);
+      delete pendingRestartReplay[records[i].assignmentId];
+    }
+  }
+
+  function propose(principal, args) {
+    principal = normalizePrincipal(principal);
+    if (!principal || !principal.sourceSessionRef) throw new Error("Project assignments require an exact session-bound Mate query.");
+    var projectSlug = clean(args.projectSlug, 120);
+    var title = clean(args.title, 160);
+    var task = clean(args.task, 12000);
+    if (!projectSlug || !title || !task) throw new Error("projectSlug, title, and task are required.");
+    var candidate = {
+      userId: principal.userId || null,
+      singleUserOwnerId: principal.singleUserOwnerId || null,
+      targetProjectSlug: projectSlug,
+    };
+    var target = exactTarget(candidate);
+    if (!target) throw new Error("Target project not found in the owned workspace.");
+    var key = sourceKey(principal);
+    var idempotency = crypto.createHash("sha256").update(key + "\u0000" + projectSlug + "\u0000" + title + "\u0000" + task).digest("hex");
+    for (var i = 0; i < records.length; i++) {
+      if (records[i].idempotencyKey === idempotency) return publicRecord(records[i]);
+      if (records[i].sourceKey === key && ACTIVE[records[i].status]) throw new Error("This conversation already has an active assignment.");
+    }
+    var now = Date.now();
+    var targetStatus = target.getStatus();
+    var record = {
+      assignmentId: "assignment_" + crypto.randomUUID(),
+      idempotencyKey: idempotency,
+      sourceKey: key,
+      userId: principal.userId || null,
+      singleUserOwnerId: principal.singleUserOwnerId || null,
+      sourceMateId: principal.mateId,
+      sourceProjectSlug: principal.sourceProjectSlug,
+      sourceSessionRef: principal.sourceSessionRef,
+      sourceRequestId: principal.sourceRequestId || null,
+      targetProjectSlug: projectSlug,
+      targetProjectTitle: clean(targetStatus.title || targetStatus.project || projectSlug, 160),
+      title: title,
+      task: task,
+      delivery: "new_session",
+      status: "proposed",
+      createdAt: now,
+      updatedAt: now,
+    };
+    if (!exactSource(record)) throw new Error("Source conversation is no longer available.");
+    records.push(record);
+    saveUser(record.userId);
+    emit(record, "project_assignment_proposal");
+    return publicRecord(record);
+  }
+
+  function proposeFollowUp(principal, args) {
+    principal = normalizePrincipal(principal);
+    if (!principal || !principal.sourceSessionRef) throw new Error("Project follow-ups require an exact session-bound Mate query.");
+    var projectSlug = clean(args.projectSlug, 120);
+    var targetSessionRef = clean(args.targetSessionRef, 100);
+    var title = clean(args.title, 160);
+    var task = clean(args.task, 12000);
+    if (!projectSlug || !targetSessionRef || !title || !task) throw new Error("projectSlug, targetSessionRef, title, and task are required.");
+    var key = sourceKey(principal);
+    var idempotency = crypto.createHash("sha256").update(key + "\u0000follow_up\u0000" + projectSlug + "\u0000" + targetSessionRef + "\u0000" + title + "\u0000" + task).digest("hex");
+    for (var i = 0; i < records.length; i++) {
+      if (records[i].idempotencyKey === idempotency) return publicRecord(records[i]);
+      if (records[i].sourceKey === key && ACTIVE[records[i].status]) throw new Error("This conversation already has an active assignment.");
+    }
+    var candidate = { userId: principal.userId || null, singleUserOwnerId: principal.singleUserOwnerId || null, targetProjectSlug: projectSlug };
+    var target = exactTarget(candidate);
+    if (!target || typeof target.inspectDelegatedFollowUp !== "function") throw new Error("Target project is unavailable for follow-ups.");
+    var inspected = target.inspectDelegatedFollowUp({ userId: principal.userId }, targetSessionRef);
+    var now = Date.now();
+    var targetStatus = target.getStatus();
+    var record = {
+      assignmentId: "assignment_" + crypto.randomUUID(), idempotencyKey: idempotency, sourceKey: key,
+      userId: principal.userId || null, singleUserOwnerId: principal.singleUserOwnerId || null,
+      sourceMateId: principal.mateId, sourceProjectSlug: principal.sourceProjectSlug,
+      sourceSessionRef: principal.sourceSessionRef, sourceRequestId: principal.sourceRequestId || null,
+      targetProjectSlug: projectSlug, targetProjectTitle: clean(targetStatus.title || targetStatus.project || projectSlug, 160),
+      targetSessionRef: inspected.sessionRef, targetSessionTitle: clean(inspected.title || "Existing session", 160),
+      title: title, task: task, delivery: "follow_up", status: "proposed", createdAt: now, updatedAt: now,
+    };
+    if (!exactSource(record)) throw new Error("Source conversation is no longer available.");
+    records.push(record);
+    saveUser(record.userId);
+    emit(record, "project_assignment_proposal");
+    return publicRecord(record);
+  }
+
+  function findOwned(userId, assignmentId) {
+    for (var i = 0; i < records.length; i++) {
+      if (records[i].assignmentId === assignmentId && records[i].userId === (userId || null)) return records[i];
+    }
+    return null;
+  }
+
+  function responseUserId(ws) {
+    return ctx.isMultiUser() && ws && ws._clayUser ? ws._clayUser.id : null;
+  }
+
+  function summarize(session) {
+    var text = "";
+    for (var i = (session && session.history || []).length - 1; i >= 0; i--) {
+      if (session.history[i].type === "delta") text = session.history[i].text + text;
+      else if (text && (session.history[i].type === "user_message" || session.history[i].type === "delegated_work" || session.history[i].type === "delegated_follow_up")) break;
+    }
+    return clean(text, 1200);
+  }
+
+  function settle(record, status, session, error) {
+    if (!ACTIVE[record.status]) return publicRecord(record);
+    record.status = status;
+    record.resultSummary = status === "completed" ? summarize(session) : "";
+    record.error = clean(error || "", 800);
+    record.updatedAt = Date.now();
+    if (unsubscribers[record.assignmentId]) unsubscribers[record.assignmentId]();
+    delete unsubscribers[record.assignmentId];
+    saveUser(record.userId);
+    emit(record);
+    return publicRecord(record);
+  }
+
+  function watch(record, manager, session) {
+    var unsubscribe = manager.subscribeSession(session.localId, function (event) {
+      if (event.type === "session_id") {
+        record.targetSessionRef = ctx.sessionRef(record.targetProjectSlug, session);
+        record.updatedAt = Date.now();
+        saveUser(record.userId);
+        emit(record);
+      } else if (event.type === "error") {
+        settle(record, "failed", session, event.text || "Assignment failed.");
+      } else if (event.type === "done" || event.type === "result") {
+        settle(record, session._lastTurnInterrupted ? "interrupted" : "completed", session, "");
+      }
+    });
+    if (unsubscribe) unsubscribers[record.assignmentId] = unsubscribe;
+  }
+
+  async function approve(record) {
+    if (record.status !== "proposed") return publicRecord(record);
+    var running = records.filter(function (item) {
+      return item.userId === record.userId && (item.status === "starting" || item.status === "running");
+    }).length;
+    if (running >= MAX_RUNNING) throw new Error("Too many assignments are already running.");
+    if (!exactSource(record)) throw new Error("Source conversation is no longer available.");
+    var target = exactTarget(record);
+    var followUp = record.delivery === "follow_up";
+    if (!target || (followUp ? typeof target.dispatchDelegatedFollowUp !== "function" : typeof target.createDelegatedSession !== "function")) throw new Error("Target project is no longer available.");
+    record.decision = "approve";
+    record.status = "starting";
+    record.updatedAt = Date.now();
+    saveUser(record.userId);
+    emit(record);
+    try {
+      var metadata = {
+        assignmentId: record.assignmentId,
+        title: record.title,
+        sourceMateId: record.sourceMateId,
+        sourceProjectSlug: record.sourceProjectSlug,
+        sourceSessionRef: record.sourceSessionRef,
+      };
+      var session;
+      if (followUp) {
+        session = await target.dispatchDelegatedFollowUp({ userId: record.userId }, record.targetSessionRef, record.task, metadata, function (existing) { watch(record, target.getSessionManager(), existing); });
+      } else {
+        session = await target.createDelegatedSession({ userId: record.userId }, record.task, metadata, function (created) { watch(record, target.getSessionManager(), created); });
+      }
+      if (record.status !== "starting") return publicRecord(record);
+      record.targetSessionRef = ctx.sessionRef(record.targetProjectSlug, session);
+      record.targetSessionId = session.localId;
+      record.status = "running";
+      record.updatedAt = Date.now();
+      saveUser(record.userId);
+      emit(record);
+    } catch (e) {
+      settle(record, "failed", null, e.message || String(e));
+    }
+    return publicRecord(record);
+  }
+
+  function cancel(record) {
+    if (record.status !== "proposed") return publicRecord(record);
+    record.decision = "cancel";
+    record.status = "cancelled";
+    record.updatedAt = Date.now();
+    saveUser(record.userId);
+    emit(record);
+    return publicRecord(record);
+  }
+
+  function getStatus(principal, assignmentId) {
+    principal = normalizePrincipal(principal);
+    if (!principal) throw new Error("Assignment not found for this conversation.");
+    var record = findOwned(principal.userId, assignmentId);
+    if (!record || record.sourceKey !== sourceKey(principal)) throw new Error("Assignment not found for this conversation.");
+    return publicRecord(record);
+  }
+
+  function validateResponseSource(ws, msg, record, routedProjectSlug) {
+    var source = exactSource(record);
+    if (!source) throw new Error("Source conversation is no longer available.");
+    var userId = responseUserId(ws);
+    if (record.userId !== (userId || null)) throw new Error("Assignment access denied.");
+    if (msg.sourceProjectSlug !== record.sourceProjectSlug || msg.sourceSessionRef !== record.sourceSessionRef) {
+      throw new Error("Assignment response does not match its source conversation.");
+    }
+    if (msg.surface === "home") {
+      var tap = ws && ws._homeChatTap;
+      if (!tap || tap.mateSlug !== record.sourceProjectSlug || tap.sessionId !== source.session.localId) {
+        throw new Error("Open the exact Home conversation before responding.");
+      }
+      if (msg.mateId !== tap.mateId || msg.sessionId !== tap.sessionReference || msg.requestId !== tap.requestId) {
+        throw new Error("Assignment response is stale for this Home conversation.");
+      }
+    } else if (routedProjectSlug !== record.sourceProjectSlug || !ws || ws._clayActiveSession !== source.session.localId) {
+      throw new Error("Open the exact project conversation before responding.");
+    }
+    return source;
+  }
+
+  async function respond(ws, msg, routedProjectSlug) {
+    var userId = responseUserId(ws);
+    var record = findOwned(userId, clean(msg.assignmentId, 100));
+    if (!record) throw new Error("Assignment proposal is stale or unavailable.");
+    validateResponseSource(ws, msg, record, routedProjectSlug);
+    var action = msg.action === "approve" ? "approve" : (msg.action === "cancel" ? "cancel" : "");
+    if (!action) throw new Error("Choose approve or cancel.");
+    if (record.status !== "proposed") {
+      if (record.decision === action) return publicRecord(record);
+      throw new Error("Assignment proposal has already been resolved.");
+    }
+    return action === "approve" ? approve(record) : cancel(record);
+  }
+
+  function handleMessage(ws, msg, routedProjectSlug) {
+    if (!msg || msg.type !== "project_assignment_response") return false;
+    respond(ws, msg, routedProjectSlug).then(function (assignment) {
+      if (ws.readyState !== 1) return;
+      if (msg.surface === "home") {
+        ws.send(JSON.stringify({ type: "home_project_assignment_status", assignment: assignment, mateId: msg.mateId, sessionId: msg.sessionId, requestId: msg.requestId }));
+      } else {
+        ws.send(JSON.stringify({ type: "project_assignment_status", assignment: assignment }));
+      }
+    }).catch(function (error) {
+      if (ws.readyState !== 1) return;
+      if (msg.surface === "home") {
+        var userId = responseUserId(ws);
+        var record = findOwned(userId, msg.assignmentId);
+        var assignment = record ? publicRecord(record) : { assignmentId: msg.assignmentId || null, status: "proposed" };
+        assignment.error = error.message || String(error);
+        ws.send(JSON.stringify({ type: "home_project_assignment_status", assignment: assignment, mateId: msg.mateId, sessionId: msg.sessionId, requestId: msg.requestId }));
+      } else {
+        ws.send(JSON.stringify({ type: "project_assignment_error", assignmentId: msg.assignmentId || null, error: error.message || String(error) }));
+      }
+    });
+    return true;
+  }
+
+  load();
+  return {
+    propose: propose,
+    proposeFollowUp: proposeFollowUp,
+    getStatus: getStatus,
+    respond: respond,
+    handleMessage: handleMessage,
+    reconcileProject: reconcileProject,
+    records: records,
+  };
+}
+
+module.exports = {
+  attachWorkspaceAssignmentService: attachWorkspaceAssignmentService,
+  userStorageKey: userStorageKey,
+};