clay-server 3.4.0 → 3.5.0-beta.1

package/lib/project-session-handoff.js

@@ -1,5 +1,19 @@
 var yoke = require("./yoke");
 var contextBuilder = require("./session-handoff-context");
+var sessionHandoffMcp = require("./session-handoff-mcp-server");
+
+var MAX_HANDOFF_CHAIN_DEPTH = 5;
+
+function toolResult(text) {
+  return Promise.resolve({ content: [{ type: "text", text: text }] });
+}
+
+function toolError(message) {
+  return Promise.resolve({
+    content: [{ type: "text", text: "Error: " + message }],
+    isError: true,
+  });
+}
 
 function hasUserContext(session) {
   var history = (session && session.history) || [];
@@ -38,7 +52,7 @@ function attachSessionHandoff(ctx) {
     }
     var ownerId = ws._clayUser && ctx.usersModule.isMultiUser() ? ws._clayUser.id : null;
     if ((source.ownerId || null) !== ownerId) throw new Error("Session access denied.");
-    return linuxUser;
+    return { linuxUser: linuxUser, vendorInfo: vendorInfo };
   }
 
   function quietRecord(session, entry) {
@@ -50,9 +64,9 @@ function attachSessionHandoff(ctx) {
     var source = sm.sessions.get(ws._clayActiveSession) || null;
     var targetVendor = typeof msg.targetVendor === "string" ? msg.targetVendor.trim() : "";
     var targetModel = typeof msg.model === "string" ? msg.model.trim() : "";
-    var linuxUser;
+    var validation;
     try {
-      linuxUser = validate(ws, source, targetVendor);
+      validation = validate(ws, source, targetVendor);
     } catch (err) {
       sendResult(ws, false, { error: err.message || String(err) });
       return;
@@ -102,6 +116,7 @@ function attachSessionHandoff(ctx) {
       cwd: ctx.cwd,
       source: source,
       targetVendor: targetVendor,
+      sourceReadTool: (validation.vendorInfo || {}).sessionBoundTools !== false,
     });
     target.isProcessing = true;
     target.lastActivity = Date.now();
@@ -128,7 +143,7 @@ function attachSessionHandoff(ctx) {
     target._queryStartTs = Date.now();
     var startPromise;
     try {
-      startPromise = sdk.startQuery(target, prompt, undefined, linuxUser);
+      startPromise = sdk.startQuery(target, prompt, undefined, validation.linuxUser);
     } catch (err) {
       failStart(err);
       return;
@@ -153,7 +168,111 @@ function attachSessionHandoff(ctx) {
     return false;
   }
 
-  return { handleMessage: handleMessage };
+  function resolveSourceChain(boundSession) {
+    var chain = [];
+    var visited = new Set();
+    var sourceSessionId = boundSession.handoff.sourceSessionId;
+    var ownerId = boundSession.ownerId || null;
+    for (var depth = 0; depth < MAX_HANDOFF_CHAIN_DEPTH; depth++) {
+      var visitKey = String(sourceSessionId);
+      if (visited.has(visitKey)) break;
+      visited.add(visitKey);
+      var source = sm.sessions.get(sourceSessionId);
+      if (!source) return { error: "Source session was not found: " + sourceSessionId };
+      if ((source.ownerId || null) !== ownerId) return { error: "Source session owner does not match this session" };
+      chain.push(source);
+      if (!source.handoff || source.handoff.sourceSessionId === undefined || source.handoff.sourceSessionId === null) break;
+      sourceSessionId = source.handoff.sourceSessionId;
+    }
+    return { chain: chain };
+  }
+
+  function findSource(chain, requestedId) {
+    if (requestedId === undefined || requestedId === null || requestedId === "") return chain[0] || null;
+    for (var i = 0; i < chain.length; i++) {
+      if (String(chain[i].localId) === String(requestedId)) return chain[i];
+    }
+    return null;
+  }
+
+  function boundedInteger(value, fallback, min, max) {
+    if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+    return Math.min(max, Math.max(min, Math.floor(value)));
+  }
+
+  function formatHistory(source, args) {
+    var history = Array.isArray(source.history) ? source.history : [];
+    var limit = boundedInteger(args.limit, 30, 1, 100);
+    var offset = typeof args.offset === "number" && Number.isFinite(args.offset)
+      ? boundedInteger(args.offset, 0, 0, history.length)
+      : Math.max(0, history.length - limit);
+    var slice = history.slice(offset, offset + limit);
+    var end = offset + slice.length;
+    var out = [];
+    out.push("# " + (source.title || "Untitled session") + " — " + (source.vendor || "unknown") + "/" + source.localId);
+    out.push("Showing entries " + (slice.length ? offset + 1 : 0) + "-" + end + " of " + history.length + "\n");
+    for (var i = 0; i < slice.length; i++) {
+      var entry = slice[i];
+      if (!entry) continue;
+      var label;
+      var text = "";
+      if (entry.type === "user_message") {
+        label = "USER";
+        text = entry.text || "";
+      } else if (entry.type === "delta") {
+        label = "ASSISTANT";
+        text = entry.text || "";
+      } else if (entry.type === "tool_executing" || entry.type === "tool_result") {
+        label = "TOOL";
+        text = (entry.name || "") + (entry.input ? " " + JSON.stringify(entry.input).substring(0, 120) : "");
+      } else {
+        continue;
+      }
+      if (text.length > 800) text = text.substring(0, 800) + "...";
+      out.push("[" + label + "] " + text);
+    }
+    return out.join("\n");
+  }
+
+  function readHandoffSource(args, boundSession) {
+    if (!boundSession) return toolError("read_handoff_source requires a session-bound tool server");
+    if (!boundSession.handoff) return toolError("this session does not have a handoff source");
+    var resolved = resolveSourceChain(boundSession);
+    if (resolved.error) return toolError(resolved.error);
+    var source = findSource(resolved.chain, args.sourceSessionId);
+    if (!source) return toolError("sourceSessionId is not in this session's handoff chain");
+    return toolResult(formatHistory(source, args));
+  }
+
+  function getToolDefs(boundSession) {
+    if (ctx.isMate) return [];
+    if (boundSession && !boundSession.handoff) return [];
+    return sessionHandoffMcp.getToolDefs({
+      read: function (args) { return readHandoffSource(args, boundSession || null); },
+    });
+  }
+
+  function createMcpServer(adapter, boundSession) {
+    if (ctx.isMate || !adapter || typeof adapter.createToolServer !== "function") return null;
+    var tools = getToolDefs(boundSession || null);
+    if (tools.length === 0) return null;
+    return adapter.createToolServer({
+      name: "clay-handoff",
+      version: "1.0.0",
+      tools: tools,
+    });
+  }
+
+  function getSystemPrompt() {
+    return "";
+  }
+
+  return {
+    createMcpServer: createMcpServer,
+    getSystemPrompt: getSystemPrompt,
+    getToolDefs: getToolDefs,
+    handleMessage: handleMessage,
+  };
 }
 
 module.exports = {

package/lib/project.js

@@ -620,6 +620,16 @@ function createProjectContext(opts) {
       }
     }
 
+    // Session-bound access to the source of a handoff (main projects only).
+    if (!isMate) {
+      try {
+        var sessionHandoffMcpConfig = _sessionHandoff.createMcpServer(adapter);
+        if (sessionHandoffMcpConfig) servers[sessionHandoffMcpConfig.name || "clay-handoff"] = sessionHandoffMcpConfig;
+      } catch (e) {
+        console.error("[project] Failed to create session handoff MCP server:", e.message);
+      }
+    }
+
     // Explicit agent signal for user-requested Markdown presentation.
     if (!isMate) {
       try {
@@ -780,7 +790,7 @@ function createProjectContext(opts) {
   //   clay-email   -> only when the user has an account or server SMTP
   //
   // forSession (optional): the session whose query these servers are mounted
-  // into. Session, notes, and document tools must know their caller, so they
+  // into. Session, notes, handoff, and document tools must know their caller, so they
   // are re-instantiated bound to that session; static instances only serve
   // descriptor listing and fail closed on calls.
   function getLocalMcpServers(forSession) {
@@ -812,6 +822,15 @@ function createProjectContext(opts) {
         }
         continue;
       }
+      if (name === "clay-handoff" && forSession) {
+        try {
+          var boundHandoff = _sessionHandoff.createMcpServer(adapter, forSession);
+          if (boundHandoff) { filtered[name] = boundHandoff; hasAny = true; }
+        } catch (e) {
+          console.error("[project] Failed to bind session handoff MCP server:", e.message);
+        }
+        continue;
+      }
       if (name === "clay-documents" && forSession) {
         try {
           var boundDocuments = _sessionDocument.createMcpServer(adapter, forSession);
@@ -879,12 +898,14 @@ function createProjectContext(opts) {
       return composeSystemPrompts([
         _sessionPair.getSystemPrompt(session),
         _sessionNotes.getSystemPrompt(session),
+        _sessionHandoff.getSystemPrompt(session),
         _sessionDocument.getSystemPrompt(session),
       ]);
     },
     getSessionToolDefs: function (session) {
       return _sessionPair.getToolDefs(session)
         .concat(_sessionNotes.getToolDefs(session))
+        .concat(_sessionHandoff.getToolDefs(session))
         .concat(_sessionDocument.getToolDefs(session));
     },
   });
@@ -1489,6 +1510,15 @@ function createProjectContext(opts) {
               inputSchema: normalizeToolSchema(noteTools[nti].inputSchema),
             });
           }
+          var handoffTools = _sessionHandoff.getToolDefs(boundSession);
+          for (var hti = 0; hti < handoffTools.length; hti++) {
+            tools.push({
+              server: "clay-handoff",
+              name: handoffTools[hti].name,
+              description: handoffTools[hti].description || handoffTools[hti].name,
+              inputSchema: normalizeToolSchema(handoffTools[hti].inputSchema),
+            });
+          }
           var documentTools = _sessionDocument.getToolDefs(boundSession);
           for (var dti = 0; dti < documentTools.length; dti++) {
             tools.push({
@@ -1509,7 +1539,7 @@ function createProjectContext(opts) {
         if (localMcp) {
           var inAppNames = Object.keys(localMcp);
           for (var i = 0; i < inAppNames.length; i++) {
-            if (inAppNames[i] === "clay-sessions" || inAppNames[i] === "clay-notes" || inAppNames[i] === "clay-documents") continue;
+            if (inAppNames[i] === "clay-sessions" || inAppNames[i] === "clay-notes" || inAppNames[i] === "clay-handoff" || inAppNames[i] === "clay-documents") continue;
             extractServerTools(inAppNames[i], localMcp[inAppNames[i]]);
           }
         }
@@ -1544,6 +1574,14 @@ function createProjectContext(opts) {
             }
           }
         }
+        if (boundSession && serverName === "clay-handoff") {
+          var handoffTools = _sessionHandoff.getToolDefs(boundSession);
+          for (var hti = 0; hti < handoffTools.length; hti++) {
+            if (handoffTools[hti].name === toolName && typeof handoffTools[hti].handler === "function") {
+              return Promise.resolve(handoffTools[hti].handler(args || {}));
+            }
+          }
+        }
         if (boundSession && serverName === "clay-documents") {
           var documentTools = _sessionDocument.getToolDefs(boundSession);
           for (var dti = 0; dti < documentTools.length; dti++) {
@@ -1552,7 +1590,7 @@ function createProjectContext(opts) {
             }
           }
         }
-        if (serverName === "clay-sessions" || serverName === "clay-notes" || serverName === "clay-documents") {
+        if (serverName === "clay-sessions" || serverName === "clay-notes" || serverName === "clay-handoff" || serverName === "clay-documents") {
           return Promise.reject(new Error("Session-bound tool requires a valid Clay session: " + serverName + "/" + toolName));
         }
         if (sessionOnly) return Promise.reject(new Error("Session tool not found: " + serverName + "/" + toolName));

package/lib/session-handoff-context.js

@@ -97,6 +97,9 @@ function buildHandoffContext(options) {
   if (latestUser) parts.push("Current user request, verbatim:\n" + latestUser);
   parts.push("Repository state at handoff:\n" + repositoryState(options.cwd));
   parts.push("Recent conversation:\n" + transcriptText(turns));
+  if (options.sourceReadTool) {
+    parts.push("The snapshot above is partial. The read_handoff_source tool from the clay-handoff MCP server can read the full original session, including summarized tool calls and older turns. Call it when the snapshot leaves a question open.");
+  }
   parts.push("Continue from the unresolved work above. Preserve the user's decisions and constraints, inspect the actual files before making assumptions, and proceed without asking the user to repeat context.");
   return trimText(parts.join("\n\n"), MAX_CONTEXT_CHARS);
 }

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

@@ -0,0 +1,36 @@
+// Session-bound access to the source of a Clay session handoff.
+
+var buildShape = require("./session-spawn-mcp-server").buildShape;
+
+var TOOL_DESCRIPTION =
+  "This session was continued from another agent's session via a context snapshot. " +
+  "That snapshot omitted tool calls and older turns. Read the original Clay session record directly, including user messages, assistant text, and summarized tool calls, regardless of which vendor produced it.";
+
+function getToolDefs(handlers) {
+  return [
+    {
+      name: "read_handoff_source",
+      description: TOOL_DESCRIPTION,
+      inputSchema: buildShape({
+        offset: {
+          type: "number",
+          description: "Skip the first N history entries. Omit to return the last limit entries.",
+        },
+        limit: {
+          type: "number",
+          description: "Maximum history entries to return. Defaults to 30 and is capped at 100.",
+        },
+        sourceSessionId: {
+          type: "string",
+          description: "Source session in this session's handoff chain. Omit to read the immediate source.",
+        },
+      }),
+      handler: function (args) { return handlers.read(args || {}); },
+    },
+  ];
+}
+
+module.exports = {
+  TOOL_DESCRIPTION: TOOL_DESCRIPTION,
+  getToolDefs: getToolDefs,
+};

package/lib/yoke/vendor-registry.js

@@ -7,6 +7,7 @@
 // codex "xhigh").
 var EFFORT_ORDER = ["minimal", "low", "medium", "high", "xhigh", "max"];
 
+// sessionBoundTools gates whether per-session MCP tool mounting reaches a vendor's process.
 var VENDOR_REGISTRY = {
   claude: {
     displayName: "Claude Code",
@@ -16,6 +17,7 @@ var VENDOR_REGISTRY = {
     sessionModes: ["gui", "tui"],
     effortLevels: ["low", "medium", "high", "xhigh", "max"],
     osUserIsolation: true,
+    sessionBoundTools: true,
     usageDashboard: {
       icon: "/claude-code-avatar.png",
       alt: "Claude Code",
@@ -32,6 +34,7 @@ var VENDOR_REGISTRY = {
     sessionModes: ["gui"],
     effortLevels: ["minimal", "low", "medium", "high", "xhigh"],
     osUserIsolation: true,
+    sessionBoundTools: false,
     usageDashboard: {
       icon: "/codex-avatar.png",
       alt: "Codex",
@@ -48,6 +51,7 @@ var VENDOR_REGISTRY = {
     sessionModes: ["gui"],
     effortLevels: ["low", "medium", "high"],
     osUserIsolation: false,
+    sessionBoundTools: false,
     usageDashboard: null,
     rateLimitTracking: false,
   },
@@ -59,6 +63,7 @@ var VENDOR_REGISTRY = {
     sessionModes: ["gui"],
     effortLevels: [],
     osUserIsolation: false,
+    sessionBoundTools: true,
     usageDashboard: null,
     rateLimitTracking: false,
   },
@@ -70,6 +75,7 @@ var VENDOR_REGISTRY = {
     sessionModes: ["gui"],
     effortLevels: [],
     osUserIsolation: false,
+    sessionBoundTools: true,
     usageDashboard: null,
     rateLimitTracking: false,
   },
@@ -81,6 +87,7 @@ var VENDOR_REGISTRY = {
     sessionModes: ["gui"],
     effortLevels: [],
     osUserIsolation: false,
+    sessionBoundTools: true,
     usageDashboard: null,
     rateLimitTracking: false,
   },
@@ -92,6 +99,7 @@ var VENDOR_REGISTRY = {
     sessionModes: ["gui"],
     effortLevels: [],
     osUserIsolation: false,
+    sessionBoundTools: true,
     usageDashboard: null,
     rateLimitTracking: false,
   },
@@ -103,6 +111,7 @@ var VENDOR_REGISTRY = {
     sessionModes: ["gui"],
     effortLevels: [],
     osUserIsolation: false,
+    sessionBoundTools: true,
     usageDashboard: null,
     rateLimitTracking: false,
   },
@@ -114,6 +123,7 @@ var VENDOR_REGISTRY = {
     sessionModes: ["gui"],
     effortLevels: [],
     osUserIsolation: false,
+    sessionBoundTools: true,
     usageDashboard: null,
     rateLimitTracking: false,
   },
@@ -125,6 +135,7 @@ var VENDOR_REGISTRY = {
     sessionModes: ["gui"],
     effortLevels: [],
     osUserIsolation: false,
+    sessionBoundTools: true,
     usageDashboard: null,
     rateLimitTracking: false,
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clay-server",
-  "version": "3.4.0",
+  "version": "3.5.0-beta.1",
   "description": "Self-hosted team workspace for Claude Code and Codex. Multi-user, browser-based, with persistent AI mates.",
   "bin": {
     "clay-server": "./bin/cli.js",