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

package/lib/session-notes-mcp-server.js

@@ -1,6 +1,8 @@
 // Sticky-note memory tools for project sessions.
 
 var buildShape = require("./session-spawn-mcp-server").buildShape;
+var z;
+try { z = require("zod"); } catch (e) { z = null; }
 
 var MEMORY_CONTRACT =
   "The sticky-note board persists across sessions and is a user-facing artifact shared with people and Clay agents, not private agent scratch space. " +
@@ -8,15 +10,28 @@ var MEMORY_CONTRACT =
   "Use Sticky Notes for preferences, reminders, undeveloped ideas, or an explicit request to remember something; confirmed Issues also get short link notes as described below. For concrete actionable bugs, improvements, or deferred implementation, an authorized Project Driver should use Project Issues. If you lack Issues authority, route the work through an eligible Project Driver. Check active notes first when a duplicate is plausible. " +
   require("./issues-filing-guidance").NOTE_GUIDANCE +
   "Never create a note merely because work is important, lengthy, spans agents or restarts, or might help another agent. Do not record completed work, implementation details, test results, investigation logs, transient blockers, conversation summaries, or announcements of your own activity. When uncertain, do not write. " +
+  "One exception: when the user explicitly asks for a working checklist, keep that one native checklist note and check its items off as they are done; never start a checklist the user did not ask for. " +
   "Updates are visible too: update only when durable state materially changes. " +
   "A note is an attention item, so finishing it means closing it, never erasing it: call close_note once the thing it is asking for is done, and the note leaves the active board while the record stays and can be reopened. Do not turn a note into a completion log instead of closing it. " +
   "Put a concise plain-text title on the first line, stay focused on one topic, and include only the context needed for future action.";
 
+var CHECKLIST_USAGE =
+  " Native checklists: pass checklist: true to create one. The first line is the title and every later non-empty, non-heading line is an item; write items as '- [ ] task' and '- [x] task' for items already done. " +
+  "To check or uncheck items, call list_notes, then pass id, that note's current version and checks with the exact item keys it returned. " +
+  "Any change to a checklist note, switching checklist mode, or changing checks needs the current version; a stale version or unknown item is refused, so list again and retry. " +
+  "Text, saved checks and colour you do not change are kept, and switching mode never erases content. Change text and checks in separate calls. " +
+  "When rewriting a checklist's text, start from checklist.effectiveText so each line's - [x] marker carries its real completion; droppedSavedChecks lists saved checks whose exact line no longer exists.";
+
+var CHECK_ENTRY = z ? z.object({
+  item: z.string().describe("Exact item key from list_notes checklist.items[].item."),
+  checked: z.boolean().describe("true marks the item done; false marks it not done."),
+}) : null;
+
 function getToolDefs(handlers) {
   return [
     {
       name: "list_notes",
-      description: MEMORY_CONTRACT + " List the notes before writing when you need to avoid duplicates or inspect full memory beyond the injected summary. Lists open notes by default; pass state to see closed ones.",
+      description: MEMORY_CONTRACT + " List the notes before writing when you need to avoid duplicates or inspect full memory beyond the injected summary. Lists open notes by default; pass state to see closed ones. Each note includes its version and checklistMode; checklist notes also include checklist.items with exact item keys, each item's effective checked value (a saved check overrides the Markdown marker), its saved value, and completed/total counts.",
       inputSchema: buildShape({
         state: { type: "string", enum: ["open", "closed", "all"], description: "Which notes to list. Defaults to open, the notes still asking for action." },
       }),
@@ -24,12 +39,16 @@ function getToolDefs(handlers) {
     },
     {
       name: "write_note",
-      description: MEMORY_CONTRACT + " Create a new note, or update an existing note by id. For notes other than confirmed Issue link notes, apply this test: would the user likely choose to keep this visible on their board next week? If the answer is unclear, do not call this tool. The 20000-character limit is an abuse guard, not a target.",
+      description: MEMORY_CONTRACT + " Create a new note, or update an existing note by id. For notes other than confirmed Issue link notes and a working checklist the user explicitly asked for, apply this test: would the user likely choose to keep this visible on their board next week? If the answer is unclear, do not call this tool. The 20000-character limit is an abuse guard, not a target." + CHECKLIST_USAGE,
       inputSchema: buildShape({
         id: { type: "string", description: "Existing note id to update. Omit to create a note." },
-        text: { type: "string", description: "User-facing sticky-note text with a concise title on the first line and only durable, action-relevant context below it." },
+        text: { type: "string", description: "User-facing sticky-note text with a concise title on the first line and only durable, action-relevant context below it. Required when creating; omit on update to keep the current text." },
         color: { type: "string", enum: ["yellow", "blue", "green", "pink", "orange", "purple"], description: "Optional sticky-note color." },
-      }, ["text"]),
+        checklist: { type: "boolean", description: "true creates or switches to a native checklist, false switches back to an ordinary note. Switching keeps the text and saved checks." },
+        version: { type: "number", description: "The note's current version from list_notes. Required for any change to a checklist note, a checklist mode switch, or checks." },
+        // buildShape returns no fields when zod is unavailable.
+        checks: { schema: CHECK_ENTRY && z.array(CHECK_ENTRY).min(1).max(1000), description: "Checklist items to check or uncheck on an existing checklist note, using exact item keys from list_notes." },
+      }),
       handler: function (args) { return handlers.write(args || {}); },
     },
     {
@@ -60,6 +79,9 @@ function getToolDefs(handlers) {
 }
 
 module.exports = {
+  // 2: native checklist fields. Conversation-scoped catalogs older than this
+  // receive the current schema through exact-query recovery.
+  CATALOG_VERSION: 2,
   MEMORY_CONTRACT: MEMORY_CONTRACT,
   getToolDefs: getToolDefs,
 };

package/lib/session-notes-writes.js

@@ -0,0 +1,88 @@
+// Pure planning for agent sticky-note updates, including native checklists.
+// Every checklist-affecting write must name the note's current version and
+// exact item keys, so a stale view can never overwrite newer content or marks.
+
+var checklist = require("./notes-checklist");
+
+var MAX_CHECKS = 1000;
+
+function validateArgs(args) {
+  if (args.checklist !== undefined && typeof args.checklist !== "boolean") return "checklist must be true or false";
+  if (args.version !== undefined && !Number.isFinite(args.version)) return "version must be the number returned by list_notes";
+  if (args.checks === undefined) return null;
+  if (!Array.isArray(args.checks) || args.checks.length === 0 || args.checks.length > MAX_CHECKS) {
+    return "checks must be a non-empty array of at most " + MAX_CHECKS + " { item, checked } entries";
+  }
+  for (var i = 0; i < args.checks.length; i++) {
+    var entry = args.checks[i];
+    if (!entry || typeof entry !== "object" || typeof entry.item !== "string" || typeof entry.checked !== "boolean") {
+      return "each checks entry needs an item key from list_notes and checked true or false";
+    }
+  }
+  return null;
+}
+
+function staleError(note) {
+  return "note " + note.id + " has changed or the version is missing; call list_notes, review its current text and items, and retry with that version";
+}
+
+// Saved marks whose exact item line no longer exists after a text change.
+function droppedChecks(note, nextText) {
+  var kept = checklist.normalizeState(note.checklistState, nextText);
+  return checklist.describe(note).filter(function (entry) {
+    return entry.saved !== null && kept[decodeURIComponent(entry.item)] === undefined;
+  }).map(function (entry) {
+    return { text: entry.text, checked: entry.saved };
+  });
+}
+
+function planUpdate(note, args, text, color) {
+  var isChecklist = note.checklistMode === true;
+  var modeChange = typeof args.checklist === "boolean" && args.checklist !== isChecklist;
+  var hasText = typeof args.text === "string";
+  var hasChecks = Array.isArray(args.checks);
+  var needsVersion = isChecklist || modeChange || hasChecks;
+  if ((needsVersion || args.version !== undefined) && args.version !== note.updatedAt) return { error: staleError(note) };
+  if (hasText && !text) return { error: "text must not be empty; close the note instead of erasing it" };
+  if (hasText && hasChecks) return { error: "change text and checks in separate calls so item keys refer to one exact version" };
+
+  var changes = {};
+  var dropped = [];
+  if (hasText && text !== note.text) {
+    changes.text = text;
+    dropped = droppedChecks(note, text);
+    if (isChecklist && !modeChange) {
+      // Storage repeats the same exact-source and version guard atomically.
+      changes.checklistEdit = true;
+      changes.checklistSource = note.text;
+      changes.checklistVersion = note.updatedAt;
+    }
+  }
+  if (color && color !== note.color) changes.color = color;
+  if (modeChange) changes.checklistMode = args.checklist;
+
+  if (hasChecks) {
+    var resultMode = modeChange ? args.checklist : isChecklist;
+    if (!resultMode) return { error: "checks apply only to checklist notes; pass checklist: true to switch this note to a checklist without changing its text" };
+    var state = checklist.normalizeState(note.checklistState, note.text);
+    var requested = Object.create(null);
+    for (var i = 0; i < args.checks.length; i++) {
+      var found = checklist.findItem(note, args.checks[i].item);
+      if (!found) return { error: "checklist item not found in note " + note.id + "; call list_notes and use its current item keys" };
+      if (requested[found.key] !== undefined && requested[found.key] !== args.checks[i].checked) {
+        return { error: "checks names the same item more than once with different values" };
+      }
+      requested[found.key] = args.checks[i].checked;
+      state[found.key] = args.checks[i].checked;
+    }
+    changes.checklistState = state;
+  }
+
+  if (!hasText && !hasChecks && !color && args.checklist === undefined) {
+    return { error: "nothing to change; pass text, color, checklist, or checks" };
+  }
+  // An identical request is acknowledged without bumping the version.
+  return { changes: Object.keys(changes).length ? changes : null, droppedSavedChecks: dropped };
+}
+
+module.exports = { validateArgs: validateArgs, planUpdate: planUpdate, MAX_CHECKS: MAX_CHECKS };

package/lib/session-permission-mode.js

@@ -7,11 +7,12 @@ function normalize(mode) {
   return null;
 }
 
-function capabilities(session, defaultVendor) {
+function capabilities(session, defaultVendor, provider) {
   var vendor = session && session.vendor || defaultVendor || "claude";
+  var contract = require("./yoke/session-tool-transport").contract(provider || vendor);
   return {
-    auto: vendor === "claude",
-    mcpOverride: vendor === "claude" && !!(session && session.queryInstance &&
+    auto: Array.isArray(contract.permissionModes) && contract.permissionModes.indexOf("auto") !== -1,
+    mcpOverride: contract.mcpPermissionOverrides === true && !!(session && session.queryInstance &&
       typeof session.queryInstance.setMcpPermissionModeOverride === "function"),
   };
 }

package/lib/session-skill-scope.js

@@ -0,0 +1,11 @@
+// Bind personal instruction reads to the existing live session/query authority.
+function bind(session, sessions, options, valid, multiUser) {
+  var owner = session.ownerId || null;
+  return Object.assign({}, options, { isAvailable: function() {
+    if (!sessions || typeof sessions.get !== "function" || sessions.get(session.localId) !== session || !valid() || (session.ownerId || null) !== owner || session.youCurator || session.sessionVisibility === "shared" || session._mcpForeignInput) return false;
+    if (owner) return require("./mcp-session-access").canUsePersonalConnections(session, sessions);
+    return !multiUser && !session.delegated && !session._delegatedBy && !session._pairDelegation
+      && !(session.history || []).some(function(entry) { return entry.type === "user_message" && entry.from && entry.from !== "default"; });
+  } });
+}
+module.exports = { bind: bind };

package/lib/session-visibility.js

@@ -36,16 +36,29 @@ function handleDefaultChange(ctx, ws, msg) {
     defaultChangeResult(ctx, ws, msg || {}, { ok: false, error: "Session visibility default must be private or shared." });
     return true;
   }
-  if (msg.slug && msg.slug !== ctx.slug) {
-    defaultChangeResult(ctx, ws, msg, { ok: false, error: "Project settings access is not permitted" });
-    return true;
+  var denied = { ok: false, error: "Project settings access is not permitted" };
+  // The target is named by the client, so it is authorised here, never trusted:
+  // another project must be accessible to this account and its own access
+  // record (owner, worktree, Mate) is the one checked below.
+  var target = msg.slug && typeof msg.slug === "string" ? msg.slug : ctx.slug;
+  var access;
+  if (target === ctx.slug) {
+    if (ctx.isMate === true) { defaultChangeResult(ctx, ws, msg, { ok: false, error: "Not supported" }); return true; }
+    access = ctx.getProjectAccess ? ctx.getProjectAccess() : null;
+  } else {
+    if (/^mate-/.test(target) || typeof ctx.getTargetAccess !== "function" ||
+        typeof ctx.canAccessProjectSlug !== "function" || ctx.canAccessProjectSlug(ws, target) !== true) {
+      defaultChangeResult(ctx, ws, msg, denied);
+      return true;
+    }
+    access = ctx.getTargetAccess(target);
+    if (!access || access.error || access.isMate === true) { defaultChangeResult(ctx, ws, msg, denied); return true; }
   }
-  if (ctx.isMate === true || !ctx.usersModule || !ctx.usersModule.isMultiUser || !ctx.usersModule.isMultiUser()) {
+  if (!ctx.usersModule || !ctx.usersModule.isMultiUser || !ctx.usersModule.isMultiUser()) {
     defaultChangeResult(ctx, ws, msg, { ok: false, error: "Not supported" });
     return true;
   }
   var user = ws && ws._clayUser && ctx.usersModule.findUserById(ws._clayUser.id);
-  var access = ctx.getProjectAccess ? ctx.getProjectAccess() : null;
   if (access && access.isWorktree === true) {
     defaultChangeResult(ctx, ws, msg, { ok: false, error: "Worktrees inherit this setting from their parent project." });
     return true;
@@ -53,16 +66,15 @@ function handleDefaultChange(ctx, ws, msg) {
   var permissions = user && ctx.usersModule.getEffectivePermissions
     ? ctx.usersModule.getEffectivePermissions(user, ctx.osUsers) : {};
   var isOwner = !!(user && access && access.ownerId && access.ownerId === user.id);
-  var isAdmin = !!(user && user.role === "admin");
-  if (!user || !permissions.projectSettings || (!isOwner && !isAdmin)) {
-    defaultChangeResult(ctx, ws, msg, { ok: false, error: "Project settings access is not permitted" });
+  if (!user || !permissions.projectSettings || !isOwner) {
+    defaultChangeResult(ctx, ws, msg, denied);
     return true;
   }
   if (typeof ctx.opts.onSetProjectSessionVisibilityDefault !== "function") {
     defaultChangeResult(ctx, ws, msg, { ok: false, error: "Not supported" });
     return true;
   }
-  var result = ctx.opts.onSetProjectSessionVisibilityDefault(ctx.slug, msg.visibility);
+  var result = ctx.opts.onSetProjectSessionVisibilityDefault(target, msg.visibility);
   defaultChangeResult(ctx, ws, msg, { ok: !!(result && result.ok), visibility: result && result.visibility, error: result && result.error });
   return true;
 }
@@ -98,7 +110,10 @@ function revokeViewers(ctx, session) {
       // Clear the server-side selection before reconnecting so no further
       // session events or input can cross the revoked access boundary.
       client._clayActiveSession = null;
-      if (client.readyState === 1) client.close(1008, "Session access changed");
+      if (client.readyState === 1) {
+        if (ctx.sendTo) ctx.sendTo(client, { type: "access_revoked", slug: ctx.slug });
+        client.close(1008, "Session access changed");
+      }
     });
   }
 }

package/lib/session-work-primary.js

@@ -0,0 +1,50 @@
+var userInput = require('./yoke/user-input');
+var TYPES = ['linear', 'issue', 'pr'];
+var GUIDANCE = ' Primary work choices belong to the user. Linking and refreshing never replace a saved primary. Only when the user explicitly requests a primary change, call the link tool with primary:true; Clay presents the exact change for human confirmation. Never request a primary change proactively. Unlinking a saved primary is refused; ask the user to choose a replacement first.';
+function kind(link) { return link.provider === 'linear' ? 'linear' : link.kind; }
+function selected(session, type) { return (session.workPrimary || {})[type] || ''; }
+function find(session, url) {
+  return (session.githubLinks || []).concat(session.linearLinks || []).find(function (link) { return link.url.toLowerCase() === String(url).toLowerCase(); });
+}
+function guardUnlink(session, url) {
+  if (TYPES.some(function (type) { return selected(session, type).toLowerCase() === url.toLowerCase(); })) throw new Error('This is a user-selected primary. Choose a replacement before unlinking it.');
+}
+function setPrimary(sm, session, url) {
+  var link = find(session, url);
+  if (!link || TYPES.indexOf(kind(link)) < 0) throw new Error('Choose an item already linked to this session.');
+  var previous = session.workPrimary;
+  session.workPrimary = Object.assign({}, previous);
+  session.workPrimary[kind(link)] = link.url;
+  try { if (sm.saveSessionFile(session) === false) throw new Error('Could not save primary work item.'); }
+  catch (error) { session.workPrimary = previous; throw error; }
+  sm.broadcastSessionList();
+  return session.workPrimary;
+}
+async function requestPrimary(ctx, session, url, authorize) {
+  var link = find(session, url);
+  if (!link) throw new Error('Link the work item before choosing it as primary.');
+  var type = kind(link), previous = selected(session, type), owner = session.ownerId;
+  if (previous.toLowerCase() === link.url.toLowerCase()) return;
+  var result = await userInput.dispatchUserInput(ctx.userInput && ctx.userInput(session), { questions: [{
+    id: 'primary', header: 'Primary work', question: 'Set ' + link.url + ' as the primary ' + (type === 'linear' ? 'Linear issue' : type === 'pr' ? 'GitHub PR' : 'GitHub issue') + ' for this conversation?',
+    options: [{ label: 'Set primary' }, { label: 'Keep current' }], allowOther: false,
+  }] }, { source: 'work-primary', signal: session.abortController && session.abortController.signal });
+  if (result.status !== 'submitted' || !result.answers.primary || result.answers.primary[0] !== 'Set primary') throw new Error('Primary selection was not changed.');
+  authorize(session);
+  if (session.taskStopRequested) throw new Error('Primary selection was not changed after Stop.');
+  if (owner !== session.ownerId || selected(session, type) !== previous) throw new Error('The owner or primary selection changed. Please retry.');
+  setPrimary(ctx.sm, session, url);
+}
+function handleMessage(ctx, ws, msg, authorize) {
+  if (msg.type !== 'session_work_primary_set') return false;
+  var response = { type: 'session_work_primary_result', requestId: msg.requestId, projectSlug: ctx.projectSlug, sessionId: msg.sessionId };
+  try {
+    var session = ctx.sm.sessions.get(msg.sessionId);
+    if (!ctx.canAccess(ws) || !session || !ctx.canRefresh(ws, session)) throw new Error('Only the session owner can choose primary work.');
+    authorize(session);
+    response.workPrimary = setPrimary(ctx.sm, session, msg.url);
+  } catch (error) { response.error = error.message; }
+  ctx.sendTo(ws, response);
+  return true;
+}
+module.exports = { GUIDANCE: GUIDANCE, guardUnlink: guardUnlink, requestPrimary: requestPrimary, handleMessage: handleMessage, setPrimary: setPrimary };