clay-server 3.4.0-beta.9 → 3.5.0-beta.1

package/lib/daemon.js

@@ -1041,64 +1041,6 @@ function shutdownProjects() {
 
 // Worktree tracking extracted to daemon-projects.js
 
-// --- Register projects ---
-var projects = config.projects || [];
-for (var i = 0; i < projects.length; i++) {
-  var p = projects[i];
-  if (fs.existsSync(p.path)) {
-    console.log("[daemon] Adding project:", p.slug, "→", p.path);
-    relay.addProject(p.path, p.slug, p.title, p.icon, p.ownerId);
-    // Discover and register worktrees for this project
-    scanAndRegisterWorktrees(relay, p.path, p.slug, p.icon, p.ownerId);
-  } else {
-    console.log("[daemon] Skipping missing project:", p.path);
-  }
-}
-
-// Migrate legacy mates storage before registration
-mates.migrateLegacyMates();
-
-// Register existing mates as projects
-if (usersModule.isMultiUser()) {
-  // Multi-user mode: iterate over all users and load each user's mates
-  var allUsers = usersModule.getAllUsers();
-  for (var ui = 0; ui < allUsers.length; ui++) {
-    var mateCtx = mates.buildMateCtx(allUsers[ui].id);
-    var userMates = mates.getAllMates(mateCtx);
-    for (var mi = 0; mi < userMates.length; mi++) {
-      var m = userMates[mi];
-      var mateDir = mates.getMateDir(mateCtx, m.id);
-      var mateSlug = "mate-" + m.id;
-      var mateName = (m.profile && m.profile.displayName) || m.name || "New Mate";
-      if (fs.existsSync(mateDir)) {
-        var mateDef = m.builtinKey ? require("./builtin-mates").getBuiltinByKey(m.builtinKey) : null;
-        var isHost = !!(mateDef && mateDef.hostAgent);
-        console.log("[daemon] Adding mate project:", mateSlug + (isHost ? " (host agent)" : ""));
-        relay.addProject(mateDir, mateSlug, mateName, null, m.createdBy, null, { isMate: true, mateDisplayName: mateName, isHostAgent: isHost });
-      }
-    }
-  }
-} else {
-  // Single-user mode: use null ctx
-  var mateCtx = mates.buildMateCtx(null);
-  var allMates = mates.getAllMates(mateCtx);
-  for (var mi = 0; mi < allMates.length; mi++) {
-    var m = allMates[mi];
-    var mateDir = mates.getMateDir(mateCtx, m.id);
-    var mateSlug = "mate-" + m.id;
-    var mateName = (m.profile && m.profile.displayName) || m.name || "New Mate";
-    if (fs.existsSync(mateDir)) {
-      var mateDef2 = m.builtinKey ? require("./builtin-mates").getBuiltinByKey(m.builtinKey) : null;
-      var isHost2 = !!(mateDef2 && mateDef2.hostAgent);
-      console.log("[daemon] Adding mate project:", mateSlug + (isHost2 ? " (host agent)" : ""));
-      relay.addProject(mateDir, mateSlug, mateName, null, m.createdBy, null, { isMate: true, mateDisplayName: mateName, isHostAgent: isHost2 });
-    }
-  }
-}
-
-// Sync ~/.clayrc on startup
-try { syncClayrc(config.projects); } catch (e) {}
-
 // --- IPC server ---
 // Clean up stale socket/config left by a previously killed daemon
 var existingConfig = loadConfig();
@@ -1334,6 +1276,64 @@ var ipc = createIPCServer(socketPath(), function (msg) {
   }
 });
 
+// --- Register projects ---
+var projects = config.projects || [];
+for (var i = 0; i < projects.length; i++) {
+  var p = projects[i];
+  if (fs.existsSync(p.path)) {
+    console.log("[daemon] Adding project:", p.slug, "→", p.path);
+    relay.addProject(p.path, p.slug, p.title, p.icon, p.ownerId);
+    // Discover and register worktrees for this project
+    scanAndRegisterWorktrees(relay, p.path, p.slug, p.icon, p.ownerId);
+  } else {
+    console.log("[daemon] Skipping missing project:", p.path);
+  }
+}
+
+// Migrate legacy mates storage before registration
+mates.migrateLegacyMates();
+
+// Register existing mates as projects
+if (usersModule.isMultiUser()) {
+  // Multi-user mode: iterate over all users and load each user's mates
+  var allUsers = usersModule.getAllUsers();
+  for (var ui = 0; ui < allUsers.length; ui++) {
+    var mateCtx = mates.buildMateCtx(allUsers[ui].id);
+    var userMates = mates.getAllMates(mateCtx);
+    for (var mi = 0; mi < userMates.length; mi++) {
+      var m = userMates[mi];
+      var mateDir = mates.getMateDir(mateCtx, m.id);
+      var mateSlug = "mate-" + m.id;
+      var mateName = (m.profile && m.profile.displayName) || m.name || "New Mate";
+      if (fs.existsSync(mateDir)) {
+        var mateDef = m.builtinKey ? require("./builtin-mates").getBuiltinByKey(m.builtinKey) : null;
+        var isHost = !!(mateDef && mateDef.hostAgent);
+        console.log("[daemon] Adding mate project:", mateSlug + (isHost ? " (host agent)" : ""));
+        relay.addProject(mateDir, mateSlug, mateName, null, m.createdBy, null, { isMate: true, mateDisplayName: mateName, isHostAgent: isHost });
+      }
+    }
+  }
+} else {
+  // Single-user mode: use null ctx
+  var mateCtx = mates.buildMateCtx(null);
+  var allMates = mates.getAllMates(mateCtx);
+  for (var mi = 0; mi < allMates.length; mi++) {
+    var m = allMates[mi];
+    var mateDir = mates.getMateDir(mateCtx, m.id);
+    var mateSlug = "mate-" + m.id;
+    var mateName = (m.profile && m.profile.displayName) || m.name || "New Mate";
+    if (fs.existsSync(mateDir)) {
+      var mateDef2 = m.builtinKey ? require("./builtin-mates").getBuiltinByKey(m.builtinKey) : null;
+      var isHost2 = !!(mateDef2 && mateDef2.hostAgent);
+      console.log("[daemon] Adding mate project:", mateSlug + (isHost2 ? " (host agent)" : ""));
+      relay.addProject(mateDir, mateSlug, mateName, null, m.createdBy, null, { isMate: true, mateDisplayName: mateName, isHostAgent: isHost2 });
+    }
+  }
+}
+
+// Sync ~/.clayrc on startup
+try { syncClayrc(config.projects); } catch (e) {}
+
 // --- Cleanup stale SDK warmup CLI session files ---
 //
 // On adapter init the SDK is given a dummy "hi" prompt to discover models,

package/lib/project-connection.js

@@ -22,12 +22,23 @@ function dispatchMessageSafely(handleMessage, sendTo, slug, ws, msg) {
   }
 }
 
-function buildInitialModelInfo(sm, initialVendor, initialModel, initialModels) {
+function buildInitialModelInfo(sm, initialVendor, initialModel, initialModels, sessionId) {
+  var model = initialModel || "";
+  var models = initialModels || [];
+  if (model && models.length > 0) {
+    var found = false;
+    for (var i = 0; i < models.length; i++) {
+      var entry = models[i];
+      if (typeof entry === "string" ? entry === model : (entry.value === model || entry.id === model || entry.resolvedModel === model)) found = true;
+    }
+    if (!found) model = typeof models[0] === "string" ? models[0] : (models[0].value || models[0].id || "");
+  }
   return {
     type: "model_info",
-    model: initialModel || "",
-    models: initialModels || [],
+    model: model,
+    models: models,
     vendor: initialVendor,
+    sessionId: sessionId || null,
     availableVendors: sm.availableVendors || [],
     installedVendors: sm.installedVendors || [],
   };
@@ -177,11 +188,12 @@ function attachConnection(ctx) {
     if (sm.slashCommands) {
       sendTo(ws, { type: "slash_commands", commands: sm.slashCommands });
     }
-    var initialModel = (restoredActive && restoredActive.model) || sm.currentModel || "";
+    var initialModel = (restoredActive && restoredActive.model) || ((sm.defaultModelByVendor || {})[initialVendor]) || "";
     // Vendor installation state is needed even before a new project has a
     // model. Always send it so reconnects cannot fall back to "Not installed."
-    sendTo(ws, buildInitialModelInfo(sm, initialVendor, initialModel, initialModels));
-    sendTo(ws, { type: "config_state", model: initialModel, mode: sm.currentPermissionMode || "default", effort: initialEffort || "medium", betas: sm.currentBetas || [], thinking: sm.currentThinking || "adaptive", thinkingBudget: sm.currentThinkingBudget || 10000 });
+    var initialModelInfo = buildInitialModelInfo(sm, initialVendor, initialModel, initialModels, restoredActive ? restoredActive.localId : null);
+    sendTo(ws, initialModelInfo);
+    sendTo(ws, { type: "config_state", model: initialModelInfo.model, vendor: initialVendor, sessionId: restoredActive ? restoredActive.localId : null, mode: sm.currentPermissionMode || "default", effort: initialEffort || "medium", betas: sm.currentBetas || [], thinking: sm.currentThinking || "adaptive", thinkingBudget: sm.currentThinkingBudget || 10000 });
     sendTo(ws, { type: "last_vendor", vendor: sm.lastVendor || "" });
     sendTo(ws, Object.assign({ type: "codex_config" }, getCodexConfig(sm)));
     sendTo(ws, { type: "term_list", terminals: tm.list() });
@@ -282,6 +294,7 @@ function attachConnection(ctx) {
       if (active.isProcessing) {
         sendTo(ws, { type: "status", status: "processing" });
       }
+      sendTo(ws, { type: "active_background_tasks", tasks: active.activeBackgroundTasks || [] });
       var pendingIds = Object.keys(active.pendingPermissions);
       for (var pi = 0; pi < pendingIds.length; pi++) {
         var p = active.pendingPermissions[pendingIds[pi]];

package/lib/project-models.js

@@ -0,0 +1,220 @@
+var yoke = require("./yoke");
+
+function modelEntryValue(entry) {
+  if (!entry) return "";
+  if (typeof entry === "string") return entry;
+  return entry.value || entry.id || "";
+}
+
+function modelEntryMatches(entry, value) {
+  if (!entry || !value) return false;
+  if (typeof entry === "string") return entry === value;
+  return entry.value === value || entry.id === value || entry.resolvedModel === value;
+}
+
+function attachModels(ctx) {
+  var cwd = ctx.cwd;
+  var slug = ctx.slug;
+  var sm = ctx.sm;
+  var sdk = ctx.sdk;
+  var adapters = ctx.adapters;
+  var sendTo = ctx.sendTo;
+  var getSessionForWs = ctx.getSessionForWs;
+  var getLinuxUserForWs = ctx.getLinuxUserForWs;
+  var serverPort = ctx.serverPort;
+  var serverTls = ctx.serverTls;
+  var serverAuthToken = ctx.serverAuthToken;
+
+  async function loadVendorModels(ws, msg) {
+    var vendor = msg.vendor || "";
+    var requestId = msg.requestId || null;
+    var loadError = null;
+    var vendorAdapter = null;
+    var session = getSessionForWs(ws);
+
+    if (!vendor) {
+      sendTo(ws, {
+        type: "model_info",
+        vendor: vendor,
+        requestId: requestId,
+        modelStatus: "error",
+        error: "No vendor was selected.",
+        model: "",
+        models: [],
+        sessionId: session ? session.localId : null,
+      });
+      return;
+    }
+
+    try {
+      var modelLinuxUser = getLinuxUserForWs(ws);
+      vendorAdapter = adapters[vendor] || null;
+      if (!vendorAdapter) {
+        vendorAdapter = await yoke.lazyCreateAdapter(adapters, vendor, {
+          cwd: cwd,
+          linuxUser: modelLinuxUser || undefined,
+          clayPort: serverPort,
+          clayTls: serverTls,
+          clayAuthToken: serverAuthToken,
+          slug: slug,
+        });
+      }
+
+      var cachedModels = (sm.modelsByVendor && sm.modelsByVendor[vendor]) || [];
+      var cachedCapabilities = sm.capabilitiesByVendor && sm.capabilitiesByVendor[vendor];
+      var needsReadyMetadata = !cachedCapabilities || cachedModels.length === 0;
+      if (vendorAdapter && needsReadyMetadata && typeof vendorAdapter.init === "function") {
+        try {
+          var readyResult = await vendorAdapter.init({
+            cwd: cwd,
+            linuxUser: modelLinuxUser || undefined,
+            clayPort: serverPort,
+            clayTls: serverTls,
+            clayAuthToken: serverAuthToken,
+            slug: slug,
+          });
+          sm.capabilitiesByVendor = sm.capabilitiesByVendor || {};
+          sm.capabilitiesByVendor[vendor] = readyResult.capabilities || {};
+          sm.modelsByVendor = sm.modelsByVendor || {};
+          if (Array.isArray(readyResult.models) && readyResult.models.length > 0) {
+            sm.modelsByVendor[vendor] = readyResult.models;
+          }
+        } catch (e) {
+          loadError = e;
+          console.error("[project-models] " + vendor + " init failed:", e.message || e);
+        }
+      }
+
+      if (vendorAdapter) {
+        sm.availableVendors = Object.keys(adapters);
+        sm.modelsByVendor = sm.modelsByVendor || {};
+        var currentModels = sm.modelsByVendor[vendor] || [];
+        if (currentModels.length === 0 && typeof vendorAdapter.supportedModels === "function") {
+          try {
+            var supported = await vendorAdapter.supportedModels();
+            if (Array.isArray(supported) && supported.length > 0) {
+              sm.modelsByVendor[vendor] = supported;
+              loadError = null;
+            }
+          } catch (e) {
+            if (!loadError) loadError = e;
+            console.error("[project-models] " + vendor + " model listing failed:", e.message || e);
+          }
+        }
+      } else {
+        loadError = new Error("The vendor adapter is unavailable.");
+      }
+    } catch (e) {
+      loadError = e;
+      console.error("[project-models] model loading failed for " + vendor + ":", e.message || e);
+    }
+
+    var vendorModels = (sm.modelsByVendor && sm.modelsByVendor[vendor]) || [];
+    var modelToSend = modelEntryValue(vendorModels[0]);
+    var preferredModel = (session && session.vendor === vendor && session.model) || (sm.defaultModelByVendor && sm.defaultModelByVendor[vendor]) || "";
+    if (preferredModel) {
+      for (var i = 0; i < vendorModels.length; i++) {
+        if (modelEntryMatches(vendorModels[i], preferredModel)) {
+          modelToSend = modelEntryValue(vendorModels[i]);
+          break;
+        }
+      }
+    }
+    var vendorInfo = yoke.getVendorInfo(vendor);
+    var displayName = vendorInfo ? vendorInfo.displayName : vendor;
+    var status = vendorModels.length > 0 ? "ready" : (loadError ? "error" : "empty");
+    var errorText = "";
+    if (status === "error") {
+      errorText = "Could not load " + displayName + " models: " + (loadError.message || loadError);
+    } else if (status === "empty") {
+      errorText = displayName + " returned no models. Check CLI authentication and retry.";
+    }
+    sendTo(ws, {
+      type: "model_info",
+      model: modelToSend,
+      models: vendorModels,
+      vendor: vendor,
+      sessionId: session ? session.localId : null,
+      capabilities: (sm.capabilitiesByVendor && sm.capabilitiesByVendor[vendor]) || {},
+      availableVendors: sm.availableVendors || [],
+      installedVendors: sm.installedVendors || [],
+      requestId: requestId,
+      modelStatus: status,
+      error: errorText,
+    });
+  }
+
+  async function selectModel(ws, msg) {
+    var session = getSessionForWs(ws);
+    if (!session) {
+      sendTo(ws, { type: "model_selection_result", requestId: msg.requestId || null, ok: false, error: "No active session." });
+      return;
+    }
+    var sessionVendor = session.vendor || sm.defaultVendor || "claude";
+    if (msg.vendor && msg.vendor !== sessionVendor) {
+      sendTo(ws, {
+        type: "model_selection_result",
+        requestId: msg.requestId || null,
+        ok: false,
+        error: "The session vendor changed before the model selection completed.",
+      });
+      return;
+    }
+    var knownModels = (sm.modelsByVendor && sm.modelsByVendor[sessionVendor]) || [];
+    if (knownModels.length > 0) {
+      var known = false;
+      for (var i = 0; i < knownModels.length; i++) {
+        if (modelEntryMatches(knownModels[i], msg.model)) {
+          known = true;
+          break;
+        }
+      }
+      if (!known) {
+        sendTo(ws, {
+          type: "model_selection_result",
+          requestId: msg.requestId || null,
+          ok: false,
+          error: "That model is not available for the selected vendor.",
+        });
+        return;
+      }
+    }
+    var result = await sdk.setModel(session, msg.model);
+    sendTo(ws, {
+      type: "model_selection_result",
+      requestId: msg.requestId || null,
+      ok: !!(result && result.ok),
+      model: result && result.model ? result.model : msg.model,
+      vendor: sessionVendor,
+      error: result && result.error ? result.error : "",
+    });
+  }
+
+  function handleMessage(ws, msg) {
+    if (msg.type === "get_vendor_models") {
+      loadVendorModels(ws, msg).catch(function(e) {
+        console.error("[project-models] Unexpected model loading failure:", e.message || e);
+      });
+      return true;
+    }
+    if (msg.type === "set_model" && msg.model) {
+      selectModel(ws, msg).catch(function(e) {
+        sendTo(ws, { type: "model_selection_result", requestId: msg.requestId || null, ok: false, error: e.message || String(e) });
+      });
+      return true;
+    }
+    return false;
+  }
+
+  return {
+    handleMessage: handleMessage,
+    loadVendorModels: loadVendorModels,
+    selectModel: selectModel,
+  };
+}
+
+module.exports = {
+  attachModels: attachModels,
+  modelEntryMatches: modelEntryMatches,
+  modelEntryValue: modelEntryValue,
+};

package/lib/project-session-handoff.js

@@ -0,0 +1,281 @@
+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) || [];
+  for (var i = 0; i < history.length; i++) {
+    if (history[i] && history[i].type === "user_message" && history[i].text) return true;
+    if (history[i] && history[i].type === "handoff_context" && history[i].request) return true;
+  }
+  return false;
+}
+
+function attachSessionHandoff(ctx) {
+  var sm = ctx.sm;
+
+  function sendResult(ws, ok, details) {
+    ctx.sendTo(ws, Object.assign({ type: "session_handoff_result", ok: ok }, details || {}));
+  }
+
+  function validate(ws, source, targetVendor) {
+    if (ctx.isMate) throw new Error("Session handoff is only available in projects.");
+    if (!source) throw new Error("No active session was found.");
+    if (ctx.splitStore && ctx.splitStore.groupForMember(source.localId)) {
+      throw new Error("Open the session by itself before continuing it in another agent.");
+    }
+    if (source.isProcessing || source._queryStarting) {
+      throw new Error("Wait for the current response to finish before continuing in another agent.");
+    }
+    if (!hasUserContext(source)) throw new Error("This session does not have any conversation to continue.");
+    if (!targetVendor) throw new Error("Choose an agent for the handoff.");
+    if (!ctx.adapters[targetVendor] || (sm.installedVendors || []).indexOf(targetVendor) === -1) {
+      throw new Error("The selected coding agent is not installed.");
+    }
+    var linuxUser = ctx.getLinuxUserForSession(source);
+    var vendorInfo = yoke.getVendorInfo(targetVendor);
+    if (linuxUser && vendorInfo && vendorInfo.osUserIsolation === false) {
+      throw new Error((vendorInfo.displayName || targetVendor) + " is not available for OS-isolated users.");
+    }
+    var ownerId = ws._clayUser && ctx.usersModule.isMultiUser() ? ws._clayUser.id : null;
+    if ((source.ownerId || null) !== ownerId) throw new Error("Session access denied.");
+    return { linuxUser: linuxUser, vendorInfo: vendorInfo };
+  }
+
+  function quietRecord(session, entry) {
+    session.history.push(entry);
+    sm.appendToSessionFile(session, entry);
+  }
+
+  function handoff(ws, msg) {
+    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 validation;
+    try {
+      validation = validate(ws, source, targetVendor);
+    } catch (err) {
+      sendResult(ws, false, { error: err.message || String(err) });
+      return;
+    }
+
+    var targetEffort = yoke.clampEffort(
+      targetVendor,
+      msg.effort || (sm.currentEffortByVendor && sm.currentEffortByVendor[targetVendor]) || sm.currentEffort || "medium"
+    ) || null;
+    var target = sm.createSessionRaw({
+      ownerId: source.ownerId || null,
+      sessionVisibility: source.sessionVisibility || "shared",
+      vendor: targetVendor,
+      model: targetModel || null,
+      effort: targetEffort,
+    });
+    var targetName = (yoke.getVendorInfo(targetVendor) || {}).displayName || targetVendor;
+    target.title = (source.title || "Continued session") + " · " + targetName;
+    target.handoff = {
+      sourceSessionId: source.localId,
+      sourceVendor: source.vendor || sm.defaultVendor || "claude",
+      createdAt: Date.now(),
+      mode: "context",
+      sourceHistoryIndex: source.history.length,
+    };
+
+    var sourceEntry = {
+      type: "handoff_created",
+      targetSessionId: target.localId,
+      targetVendor: targetVendor,
+      targetTitle: target.title,
+      _ts: Date.now(),
+    };
+    var targetEntry = {
+      type: "handoff_context",
+      sourceSessionId: source.localId,
+      sourceVendor: target.handoff.sourceVendor,
+      sourceTitle: source.title || "Untitled session",
+      targetVendor: targetVendor,
+      request: contextBuilder.latestUserRequest(source.history),
+      _ts: Date.now(),
+    };
+    quietRecord(source, sourceEntry);
+    quietRecord(target, targetEntry);
+
+    var prompt = contextBuilder.buildHandoffContext({
+      cwd: ctx.cwd,
+      source: source,
+      targetVendor: targetVendor,
+      sourceReadTool: (validation.vendorInfo || {}).sessionBoundTools !== false,
+    });
+    target.isProcessing = true;
+    target.lastActivity = Date.now();
+    target.sentToolResults = {};
+    sm.switchSession(target.localId, ws);
+    if (typeof ctx.onProcessingChanged === "function") ctx.onProcessingChanged();
+    sendResult(ws, true, {
+      sourceSessionId: source.localId,
+      targetSessionId: target.localId,
+      targetVendor: targetVendor,
+    });
+
+    var sdk = ctx.getSdk();
+    function failStart(err) {
+      target.isProcessing = false;
+      sm.sendAndRecord(target, { type: "error", text: "Could not start the handoff session: " + (err.message || String(err)) });
+      if (typeof ctx.onProcessingChanged === "function") ctx.onProcessingChanged();
+      sm.broadcastSessionList();
+    }
+    if (!sdk || typeof sdk.startQuery !== "function") {
+      failStart(new Error("SDK bridge is not ready."));
+      return;
+    }
+    target._queryStartTs = Date.now();
+    var startPromise;
+    try {
+      startPromise = sdk.startQuery(target, prompt, undefined, validation.linuxUser);
+    } catch (err) {
+      failStart(err);
+      return;
+    }
+    Promise.resolve(startPromise).catch(failStart);
+  }
+
+  function handleMessage(ws, msg) {
+    if (msg.type === "handoff_session_options") {
+      ctx.sendTo(ws, {
+        type: "handoff_session_options",
+        installedVendors: sm.installedVendors || [],
+        modelsByVendor: sm.modelsByVendor || {},
+        capabilitiesByVendor: sm.capabilitiesByVendor || {},
+      });
+      return true;
+    }
+    if (msg.type === "handoff_session") {
+      handoff(ws, msg);
+      return true;
+    }
+    return false;
+  }
+
+  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 = {
+  attachSessionHandoff: attachSessionHandoff,
+  hasUserContext: hasUserContext,
+};