clay-server 4.2.0 → 4.3.0-beta.10

package/lib/session-handoff-discovery.js

@@ -0,0 +1,443 @@
+// Bounded, query-bound discovery of other visible Driver sessions.
+
+var sessionDriverEligibility = require("./session-driver-eligibility");
+var sessionRef = require("./workspace-query-service").sessionRef;
+
+var MAX_RESULTS = 20;
+var MAX_QUERY_CHARS = 200;
+var MAX_EXCERPT_CHARS = 1200;
+var MAX_RESPONSE_CHARS = 15000;
+var MAX_QUERY_RESPONSE_CHARS = 32000;
+var MAX_CALLS = 8;
+var UNVERSIONED_QUERY = "__unversioned_query__";
+var CROSS_PROJECT_LIMITATION = "Only sessions in this project are available.";
+var EXHAUSTED_TEXT = "Retrieval budget exhausted for this query.";
+
+function clean(value, limit) {
+  if (typeof value !== "string") return "";
+  var result = value.replace(/\u0000/g, "").trim();
+  if (result.length <= limit) return result;
+  return result.substring(0, Math.max(0, limit - 3)) + "...";
+}
+
+function resultResponse(text) {
+  return { content: [{ type: "text", text: text }] };
+}
+
+function errorResponse(text) {
+  return { content: [{ type: "text", text: "Error: " + text }], isError: true };
+}
+
+function responseSize(response) {
+  return JSON.stringify(response).length;
+}
+
+function isExcludedDriverIdentity(session) {
+  return !!(session && (
+    session.hidden === true || session.delegated === true ||
+    session._pairDelegation || session._delegatedBy ||
+    session.scheduledTaskRun || session.projectLogReview
+  ));
+}
+
+function currentGeneration(session) {
+  if (!session) return null;
+  if (Number.isInteger(session._sdkQueryGeneration)) return session._sdkQueryGeneration;
+  if (Number.isInteger(session._queryGeneration)) return session._queryGeneration;
+  return null;
+}
+
+function entryKey(projectSlug, source, index) {
+  return "entry:" + sessionRef(projectSlug, source) + ":" + index;
+}
+
+function timestamp(entry, source) {
+  var value = entry && entry._ts;
+  if (typeof value !== "number" || !Number.isFinite(value)) value = source.lastActivity || source.createdAt || 0;
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function attachSessionHandoffDiscovery(ctx) {
+  var sm = ctx.sm;
+  var budgets = new WeakMap();
+
+  function isDriver(session) {
+    if (!sessionDriverEligibility.isEligibleDriverSession(session)) return false;
+    if (isExcludedDriverIdentity(session) || session.isMate === true) return false;
+    if (typeof ctx.isDriverOperatedSession !== "function") return true;
+    try {
+      return ctx.isDriverOperatedSession(session) !== true;
+    } catch (e) {
+      return false;
+    }
+  }
+
+  function stateFor(boundSession, generation) {
+    var current = currentGeneration(boundSession);
+    if (generation === UNVERSIONED_QUERY && current !== null) return null;
+    if (generation !== UNVERSIONED_QUERY && generation !== undefined && generation !== null && current !== generation) return null;
+    var key = generation !== undefined && generation !== null
+      ? generation
+      : (current === null ? "unversioned" : current);
+    var state = budgets.get(boundSession);
+    if (!state || state.key !== key) {
+      state = { key: key, calls: 0, used: 0, seen: Object.create(null), exhausted: false };
+      budgets.set(boundSession, state);
+    }
+    return state;
+  }
+
+  function authorize(boundSession, candidate) {
+    if (!boundSession || !sm || !sm.sessions) return false;
+    if (sm.sessions.get(boundSession.localId) !== boundSession) return false;
+    if (ctx.isMate || !isDriver(boundSession) || typeof ctx.getProjectAccess !== "function") return false;
+    var access;
+    try {
+      access = ctx.getProjectAccess();
+    } catch (e) {
+      return false;
+    }
+    if (!access || access.error) return false;
+    var actorId = boundSession.ownerId || null;
+    if (typeof ctx.isMultiUser === "function" && ctx.isMultiUser()) {
+      if (!actorId || typeof ctx.findUserById !== "function" || typeof ctx.canAccessSession !== "function") return false;
+      var actor = ctx.findUserById(actorId);
+      if (!actor || actor.active === false || actor.disabled === true) return false;
+      try {
+        if (ctx.canAccessSession(actorId, boundSession, access) !== true) return false;
+        if (candidate === boundSession) return true;
+        return !!candidate && isDriver(candidate) && ctx.canAccessSession(actorId, candidate, access) === true;
+      } catch (e2) {
+        return false;
+      }
+    }
+    if (!candidate || !isDriver(candidate)) return false;
+    if (candidate === boundSession) return true;
+    return !candidate.ownerId || candidate.ownerId === actorId;
+  }
+
+  function candidates(boundSession) {
+    if (!authorize(boundSession, boundSession)) return [];
+    var result = [];
+    sm.sessions.forEach(function (candidate) {
+      if (candidate !== boundSession && authorize(boundSession, candidate)) result.push(candidate);
+    });
+    result.sort(function (a, b) {
+      var activity = (b.lastActivity || b.createdAt || 0) - (a.lastActivity || a.createdAt || 0);
+      if (activity) return activity;
+      return sessionRef(ctx.projectSlug, a) < sessionRef(ctx.projectSlug, b) ? -1 : 1;
+    });
+    return result;
+  }
+
+  function metadata(boundSession, candidate) {
+    if (!authorize(boundSession, candidate)) return null;
+    return {
+      sessionRef: sessionRef(ctx.projectSlug, candidate),
+      title: clean(candidate.title || "New Session", 160),
+      vendor: clean(candidate.vendor || "", 40) || null,
+      createdAt: candidate.createdAt || 0,
+      lastActivity: candidate.lastActivity || candidate.createdAt || 0,
+    };
+  }
+
+  function refusal(message) {
+    return errorResponse(message || EXHAUSTED_TEXT);
+  }
+
+  function beginCall(boundSession, generation) {
+    var state = stateFor(boundSession, generation);
+    if (!state) return { refusal: refusal("This retrieval tool belongs to an older query.") };
+    if (state.exhausted || state.calls >= MAX_CALLS) {
+      state.exhausted = true;
+      return { state: state, refusal: refusal(EXHAUSTED_TEXT) };
+    }
+    state.calls++;
+    if (state.used >= MAX_QUERY_RESPONSE_CHARS) {
+      state.exhausted = true;
+      return { state: state, refusal: refusal(EXHAUSTED_TEXT) };
+    }
+    return { state: state };
+  }
+
+  function budgetMetadata(state) {
+    return {
+      maxResponseChars: MAX_RESPONSE_CHARS,
+      maxQueryChars: MAX_QUERY_RESPONSE_CHARS,
+      usedChars: state.used,
+      maxCalls: MAX_CALLS,
+      calls: state.calls,
+      query: state.key,
+    };
+  }
+
+  function encodePayload(state, payload) {
+    var response;
+    var size = 0;
+    for (var i = 0; i < 8; i++) {
+      response = resultResponse(JSON.stringify(payload));
+      size = responseSize(response);
+      if (!payload.budget || payload.budget.usedChars === state.used + size) break;
+      payload.budget.usedChars = state.used + size;
+    }
+    return { response: response, size: size };
+  }
+
+  function finishPayload(call, payload, arrayName, keys) {
+    var state = call.state;
+    var available = Math.min(MAX_RESPONSE_CHARS, MAX_QUERY_RESPONSE_CHARS - state.used);
+    var encoded = encodePayload(state, payload);
+    while (encoded.size > available && arrayName && payload[arrayName].length > 0) {
+      payload[arrayName].pop();
+      keys.pop();
+      payload.truncated = true;
+      encoded = encodePayload(state, payload);
+    }
+    if (encoded.size > available) {
+      state.exhausted = true;
+      return refusal(EXHAUSTED_TEXT);
+    }
+    state.used += encoded.size;
+    for (var i = 0; i < keys.length; i++) state.seen[keys[i]] = true;
+    if (state.used >= MAX_QUERY_RESPONSE_CHARS || state.calls >= MAX_CALLS) state.exhausted = true;
+    return encoded.response;
+  }
+
+  function finishError(call, message) {
+    if (call.refusal) return call.refusal;
+    var state = call.state;
+    var response = errorResponse(clean(message || "Retrieval failed.", 500));
+    var size = responseSize(response);
+    if (size > MAX_QUERY_RESPONSE_CHARS - state.used) {
+      state.exhausted = true;
+      return refusal(EXHAUSTED_TEXT);
+    }
+    state.used += size;
+    if (state.used >= MAX_QUERY_RESPONSE_CHARS || state.calls >= MAX_CALLS) state.exhausted = true;
+    return response;
+  }
+
+  function basePayload(state) {
+    return {
+      projectSlug: ctx.projectSlug,
+      crossProject: false,
+      limitation: CROSS_PROJECT_LIMITATION,
+      budget: budgetMetadata(state),
+    };
+  }
+
+  function list(boundSession, args, generation) {
+    var call = beginCall(boundSession, generation);
+    if (call.refusal) return call.refusal;
+    if (!authorize(boundSession, boundSession)) return finishError(call, "Driver session access denied.");
+    var all = candidates(boundSession);
+    var payload = basePayload(call.state);
+    payload.sessions = [];
+    payload.scannedSessions = all.length;
+    payload.truncated = false;
+    payload.budget.maxResults = MAX_RESULTS;
+    var keys = [];
+    for (var i = 0; i < all.length && payload.sessions.length < MAX_RESULTS; i++) {
+      var item = metadata(boundSession, all[i]);
+      var key = item ? "source:" + item.sessionRef : null;
+      if (!item || call.state.seen[key]) continue;
+      payload.sessions.push(item);
+      keys.push(key);
+    }
+    payload.truncated = all.length > payload.sessions.length;
+    return finishPayload(call, payload, "sessions", keys);
+  }
+
+  function search(boundSession, args, generation) {
+    var call = beginCall(boundSession, generation);
+    if (call.refusal) return call.refusal;
+    if (!authorize(boundSession, boundSession)) return finishError(call, "Driver session access denied.");
+    var query = clean(args && args.query || "", MAX_QUERY_CHARS).toLowerCase();
+    if (!query) return finishError(call, "A keyword query is required.");
+    var all = candidates(boundSession);
+    var payload = basePayload(call.state);
+    payload.query = query;
+    payload.results = [];
+    payload.scannedSessions = all.length;
+    payload.truncated = false;
+    payload.budget.maxResults = MAX_RESULTS;
+    payload.budget.maxExcerptChars = MAX_EXCERPT_CHARS;
+    var keys = [];
+    for (var i = 0; i < all.length && payload.results.length < MAX_RESULTS; i++) {
+      var candidate = all[i];
+      var item = metadata(boundSession, candidate);
+      if (!item) continue;
+      var history = Array.isArray(candidate.history) ? candidate.history : [];
+      for (var h = 0; h < history.length && payload.results.length < MAX_RESULTS; h++) {
+        var entry = history[h];
+        if (!entry || (entry.type !== "user_message" && entry.type !== "delta")) continue;
+        if (typeof entry.text !== "string") continue;
+        var match = entry.text.toLowerCase().indexOf(query);
+        if (match === -1) continue;
+        var key = entryKey(ctx.projectSlug, candidate, h);
+        if (call.state.seen[key]) continue;
+        var start = Math.max(0, match - 180);
+        var excerpt = clean(entry.text.substring(start, start + MAX_EXCERPT_CHARS), MAX_EXCERPT_CHARS);
+        if (start > 0) excerpt = "..." + excerpt;
+        var date = timestamp(entry, candidate);
+        payload.results.push({
+          sessionRef: item.sessionRef,
+          title: item.title,
+          vendor: item.vendor,
+          role: entry.type === "user_message" ? "user" : "assistant",
+          entryIndex: h,
+          date: date,
+          excerpt: excerpt,
+          citation: item.sessionRef + " entry " + h + " (" + new Date(date).toISOString() + ")",
+        });
+        keys.push(key);
+      }
+    }
+    payload.truncated = payload.results.length >= MAX_RESULTS;
+    return finishPayload(call, payload, "results", keys);
+  }
+
+  function read(boundSession, args, generation) {
+    var call = beginCall(boundSession, generation);
+    if (call.refusal) return call.refusal;
+    if (!authorize(boundSession, boundSession)) return finishError(call, "Driver session access denied.");
+    var ref = args && args.sessionRef;
+    var all = candidates(boundSession);
+    var candidate = null;
+    for (var i = 0; i < all.length; i++) {
+      if (sessionRef(ctx.projectSlug, all[i]) === ref) candidate = all[i];
+    }
+    if (!candidate || !authorize(boundSession, candidate)) {
+      return finishError(call, "Session not found or not shared with this Driver.");
+    }
+    var item = metadata(boundSession, candidate);
+    var history = Array.isArray(candidate.history) ? candidate.history : [];
+    var limit = Number.isFinite(args && args.limit) ? Math.max(1, Math.min(20, Math.floor(args.limit))) : 5;
+    var start;
+    if (Number.isInteger(args && args.entryIndex)) start = Math.max(0, args.entryIndex - 2);
+    else if (Number.isInteger(args && args.offset)) start = Math.max(0, args.offset);
+    else start = 0;
+    start = Math.min(history.length, start);
+    var end = Math.min(history.length, start + limit);
+    var payload = basePayload(call.state);
+    payload.session = item;
+    payload.excerpts = [];
+    payload.requestedStart = start;
+    payload.requestedEnd = end;
+    payload.truncated = end < history.length;
+    payload.budget.maxExcerptChars = MAX_EXCERPT_CHARS;
+    var keys = [];
+    for (var h = start; h < end; h++) {
+      var entry = history[h];
+      if (!entry || (entry.type !== "user_message" && entry.type !== "delta")) continue;
+      if (typeof entry.text !== "string") continue;
+      var key = entryKey(ctx.projectSlug, candidate, h);
+      if (call.state.seen[key]) continue;
+      var date = timestamp(entry, candidate);
+      payload.excerpts.push({
+        entryIndex: h,
+        role: entry.type === "user_message" ? "user" : "assistant",
+        date: date,
+        excerpt: clean(entry.text, MAX_EXCERPT_CHARS),
+        citation: item.sessionRef + " entry " + h,
+      });
+      keys.push(key);
+    }
+    return finishPayload(call, payload, "excerpts", keys);
+  }
+
+  function legacyLine(entry) {
+    if (!entry) return null;
+    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";
+      var input = "";
+      try {
+        input = entry.input ? JSON.stringify(entry.input) || "" : "";
+      } catch (e) {
+        input = "[unserializable input]";
+      }
+      text = (entry.name || "") + (input ? " " + input.substring(0, 120) : "");
+    } else {
+      return null;
+    }
+    return "[" + label + "] " + clean(text, 800);
+  }
+
+  function legacy(boundSession, source, args, generation) {
+    var call = beginCall(boundSession, generation);
+    if (call.refusal) return call.refusal;
+    if (!authorize(boundSession, boundSession) || !authorize(boundSession, source)) {
+      return finishError(call, "Source session access denied.");
+    }
+    var history = Array.isArray(source.history) ? source.history : [];
+    var limit = Number.isFinite(args && args.limit) ? Math.max(1, Math.min(100, Math.floor(args.limit))) : 30;
+    var offset = Number.isFinite(args && args.offset)
+      ? Math.max(0, Math.min(history.length, Math.floor(args.offset)))
+      : Math.max(0, history.length - limit);
+    var end = Math.min(history.length, offset + limit);
+    var header = "# " + clean(source.title || "Untitled session", 160) + " — " +
+      clean(source.vendor || "unknown", 40) + "/" + source.localId + "\n" +
+      "Showing entries " + (history.length ? offset + 1 : 0) + "-" + end + " of " + history.length + "\n";
+    var lines = [];
+    var keys = [];
+    for (var i = offset; i < end; i++) {
+      var line = legacyLine(history[i]);
+      var key = entryKey(ctx.projectSlug, source, i);
+      if (!line || call.state.seen[key]) continue;
+      lines.push(line);
+      keys.push(key);
+    }
+    var available = Math.min(MAX_RESPONSE_CHARS, MAX_QUERY_RESPONSE_CHARS - call.state.used);
+    var response = resultResponse(header + "\n" + lines.join("\n"));
+    while (responseSize(response) > available && lines.length > 0) {
+      lines.pop();
+      keys.pop();
+      response = resultResponse(header + "\n" + lines.join("\n") + "\n[truncated]");
+    }
+    var size = responseSize(response);
+    if (size > available) {
+      call.state.exhausted = true;
+      return refusal(EXHAUSTED_TEXT);
+    }
+    call.state.used += size;
+    for (var k = 0; k < keys.length; k++) call.state.seen[keys[k]] = true;
+    if (call.state.used >= MAX_QUERY_RESPONSE_CHARS || call.state.calls >= MAX_CALLS) call.state.exhausted = true;
+    return response;
+  }
+
+  function fail(boundSession, generation, message) {
+    var call = beginCall(boundSession, generation);
+    return finishError(call, message);
+  }
+
+  return {
+    authorize: authorize,
+    captureGeneration: function (session) {
+      var generation = currentGeneration(session);
+      return generation === null ? UNVERSIONED_QUERY : generation;
+    },
+    currentGeneration: currentGeneration,
+    fail: fail,
+    legacy: legacy,
+    list: list,
+    read: read,
+    search: search,
+  };
+}
+
+module.exports = {
+  attachSessionHandoffDiscovery: attachSessionHandoffDiscovery,
+  MAX_CALLS: MAX_CALLS,
+  MAX_QUERY_RESPONSE_CHARS: MAX_QUERY_RESPONSE_CHARS,
+  MAX_RESPONSE_CHARS: MAX_RESPONSE_CHARS,
+  MAX_RESULTS: MAX_RESULTS,
+  UNVERSIONED_QUERY: UNVERSIONED_QUERY,
+};

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

@@ -5,12 +5,16 @@ 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.";
+var BUDGET_DESCRIPTION =
+  " Responses are capped at 15,000 serialized characters, 32,000 serialized characters and 8 calls per query. " +
+  "After exhaustion, calls return one constant refusal; repeated refusals are outside the aggregate cap, so callers must stop.";
 
 function getToolDefs(handlers) {
-  return [
+  var tools = [];
+  if (handlers.read) tools.push(
     {
       name: "read_handoff_source",
-      description: TOOL_DESCRIPTION,
+      description: TOOL_DESCRIPTION + BUDGET_DESCRIPTION,
       inputSchema: buildShape({
         offset: {
           type: "number",
@@ -26,8 +30,32 @@ function getToolDefs(handlers) {
         },
       }),
       handler: function (args) { return handlers.read(args || {}); },
-    },
-  ];
+    }
+  );
+  if (handlers.listOtherDrivers) tools.push({
+    name: "list_other_driver_sessions",
+    description: "List bounded metadata for other visible Driver sessions in this project. Shared-session access is checked at call time; cross-project discovery is unavailable." + BUDGET_DESCRIPTION,
+    inputSchema: buildShape({ limit: { type: "number", description: "Ignored beyond the server cap of 20." } }),
+    handler: function (args) { return handlers.listOtherDrivers(args || {}); },
+  });
+  if (handlers.searchOtherDrivers) tools.push({
+    name: "search_other_driver_sessions",
+    description: "Search user and assistant text in other visible Driver sessions in this project, returning bounded excerpts with session, entry, and date citations. Cross-project search is unavailable." + BUDGET_DESCRIPTION,
+    inputSchema: buildShape({ query: { type: "string", description: "Keyword to search." } }),
+    handler: function (args) { return handlers.searchOtherDrivers(args || {}); },
+  });
+  if (handlers.readOtherDriver) tools.push({
+    name: "read_other_driver_session",
+    description: "Read a bounded history window from one visible other Driver session by opaque session reference. Already returned entries are skipped without dropping unseen entries from the requested window. Cross-project reads are unavailable." + BUDGET_DESCRIPTION,
+    inputSchema: buildShape({
+      sessionRef: { type: "string", description: "Opaque session reference from discovery or search." },
+      entryIndex: { type: "number", description: "Center a window near this cited history entry." },
+      offset: { type: "number", description: "Start the window at this history entry when entryIndex is omitted." },
+      limit: { type: "number", description: "History positions in the window. Defaults to 5 and is capped at 20." },
+    }),
+    handler: function (args) { return handlers.readOtherDriver(args || {}); },
+  });
+  return tools;
 }
 
 module.exports = {

package/lib/session-pair-factory.js

@@ -34,6 +34,7 @@ var driverEligibility = require("./session-driver-eligibility");
 var models = require("./project-models");
 var yoke = require("./yoke");
 var sessionProvenance = require("./session-provenance");
+var splitRoles = require("./session-split-group-roles");
 
 function attachPairFactory(ctx) {
   var sm = ctx.sm;
@@ -230,6 +231,69 @@ function attachPairFactory(ctx) {
     return created;
   }
 
+  function createUnpairedWorkerForDriver(driver, args) {
+    var runtime = preflightWorkerForDriver(driver, args);
+    var worker = sm.createSessionRaw({
+      ownerId: driver.ownerId || null,
+      vendor: runtime.vendor,
+      model: runtime.model,
+      effort: runtime.effort,
+    });
+    try {
+      worker.title = "Split Worker · " + ((yoke.getVendorInfo(runtime.vendor) || {}).displayName || runtime.vendor);
+      if (runtime.explicitEffort) worker.loopSettings = { effort: runtime.effort };
+      sessionProvenance.markWorker(driver, worker, sm.sessions);
+      if (typeof sm.saveSessionFile === "function") {
+        if (sm.saveSessionFile(driver) === false || sm.saveSessionFile(worker) === false) {
+          throw new Error("Split Worker session persistence returned false");
+        }
+      }
+      return worker;
+    } catch (error) {
+      removeCreated(worker);
+      throw error;
+    }
+  }
+
+  function exactMutation(driver, worker, args, method) {
+    var group = store.groupForMember(driver.localId);
+    if (!group) throw new Error("split group not found");
+    var role = splitRoles.normalizePair(group.pair, group.members);
+    if (!role.ok || role.kind === "adhoc") throw new Error("split group roles changed");
+    var created = createUnpairedWorkerForDriver(driver, args);
+    var request = {
+      groupId: group.id,
+      driverId: driver.localId,
+      driverOriginId: driver.sessionOriginId || null,
+      expectedGroup: args.expectedGroup || group,
+      expectedWorkerIds: Array.isArray(args.expectedWorkerIds) ? args.expectedWorkerIds.slice() : role.workerIds.slice(),
+      newWorkerId: created.localId,
+      newWorkerOriginId: created.sessionOriginId || null,
+    };
+    if (worker) {
+      request.workerId = worker.localId;
+      request.workerOriginId = worker.sessionOriginId || null;
+      request.generation = worker._pairGeneration ||
+        worker.sessionProvenance && worker.sessionProvenance.generation || null;
+    }
+    var result = store[method](driver.ownerId || null, request, ctx.multiWorkerFeature);
+    if (!result.ok) {
+      removeCreated(created);
+      throw new Error(result.error);
+    }
+    sm.broadcastSessionList();
+    sm.sendToSession(driver, { type: "pair_session_created", ok: true, group: result.group });
+    return { driver: driver, worker: created, group: result.group };
+  }
+
+  function addWorkerForDriver(driver, args) {
+    return exactMutation(driver, null, args, "addWorker");
+  }
+
+  function replaceWorkerForDriver(driver, worker, args) {
+    return exactMutation(driver, worker, args, "replaceWorker");
+  }
+
   function createOwnedPair(ownerId, args) {
     if (ctx.isMate) throw new Error("Pair sessions are only available in projects");
     var request = args || {};
@@ -276,6 +340,8 @@ function attachPairFactory(ctx) {
     createPair: createPair,
     createPairRecord: createPairRecord,
     createWorkerForDriver: createWorkerForDriver,
+    addWorkerForDriver: addWorkerForDriver,
+    replaceWorkerForDriver: replaceWorkerForDriver,
     createOwnedPair: createOwnedPair,
     removeOwnedPair: removeOwnedPair,
     preflightRuntime: preflightRuntime,

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

@@ -19,31 +19,33 @@ function getToolDefs(handlers, options) {
       description: "Delegate one concrete follow-up task to the existing visible Split Worker. This tool is exposed only after the user has configured and accepted an exact pair. A completed turn does not end the Split Worker session: reuse the same Split Worker for follow-up implementation and corrections instead of taking over its work. Detached completions are pushed back automatically. A delegated turn cannot delegate back, so keep orchestration one hop deep.",
       inputSchema: buildShape({
         message: { type: "string", description: "The complete task or question for the partner." },
-        wait: { type: "boolean", description: "Wait for the partner's turn to finish. Defaults to true." },
+        wait: { type: "boolean", description: "Wait for the partner's turn to finish. Defaults to false; set true for an explicit blocking wait." },
         timeoutSeconds: { type: "number", description: "Maximum wait in seconds, from 1 to 900. Defaults to 300." },
         operationId: { type: "string", description: "Optional stable id for this delegation. Reusing it within the same human turn returns the original operation instead of sending twice." },
         taskId: { type: "string", description: "Optional stable task id for generation and completion correlation." },
+        workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." },
       }, ["message"]),
       handler: function (args) { return handlers.send(args || {}); },
     },
     {
       name: "read_partner",
-      description: "Read the Split Worker's current status and recent conversation turns, plus the same bounded capacity report partner_status returns. Use this for an interim check after a non-waiting delegation or timeout; completed results are pushed automatically.",
+      description: "Read the Split Worker's current status and recent conversation turns, plus the same bounded capacity report partner_status returns. Use only for a requested status, concrete failure or stall diagnosis, or capacity/queue decision; do not poll routinely. Completed results are pushed automatically.",
       inputSchema: buildShape({
         lastTurns: { type: "number", description: "Number of recent user-message-delimited turns, from 0 to 5. Use 0 for status only. Defaults to 1." },
+        workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." },
       }),
       handler: function (args) { return handlers.read(args || {}); },
     },
     {
       name: "interrupt_partner",
       description: "Interrupt the Split Worker's current task. Use this when the task is going in the wrong direction, needs to be reprioritized, or must stop before the next instruction. The Split Worker returns any partial result to you for review.",
-      inputSchema: buildShape({ reason: { type: "string", description: "Why the Driver is interrupting this task." } }),
+      inputSchema: buildShape({ reason: { type: "string", description: "Why the Driver is interrupting this task." }, workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." } }),
       handler: function (args) { return handlers.interrupt(args || {}); },
     },
     {
       name: "close_partner",
       description: "Close the visible Split Worker pane and dissolve the Driver/Split Worker pair while preserving both session histories. If the Split Worker is still running, Clay interrupts it before closing the pair.",
-      inputSchema: buildShape({}),
+      inputSchema: buildShape({ workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." } }),
       handler: function (args) { return handlers.close(args || {}); },
     },
   ];
@@ -55,13 +57,14 @@ function getToolDefs(handlers, options) {
       inputSchema: buildShape({
         message: { type: "string", description: "Bounded correction or context for the current active Worker turn." },
         requestId: { type: "string", description: "Optional stable request id. Reuse it to deduplicate a retried delivery within this human turn." },
+        workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." },
       }, ["message"]),
       handler: function (args) { return handlers.message(args || {}); },
     },
     {
       name: "partner_status",
       description: "Bounded capacity and continuity report for your Split Worker, for deciding reuse against replacement: context tokens used and the ratio of its window, current task and activity, vendor/model/effort, history size and idle time, whether it is safe to replace right now, and your own recorded results for earlier Worker generations. Returns no transcript. Prefer this over reading turns when you only need to decide.",
-      inputSchema: buildShape({}),
+      inputSchema: buildShape({ workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." } }),
       handler: function (args) { return handlers.status(args || {}); },
     },
     {
@@ -80,6 +83,7 @@ function getToolDefs(handlers, options) {
         },
         operationId: { type: "string", description: "Optional stable id for this replacement. Reusing it within the same human turn returns the original operation instead of replacing twice." },
         supersedeProposalId: { type: "string", description: "Exact pending replacement proposal id to supersede with this new configuration." },
+        workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." },
       }, ["message", "recommendationRationale"]),
       handler: function (args) { return handlers.replace(args || {}); },
     },
@@ -90,6 +94,7 @@ function getToolDefs(handlers, options) {
         outcome: { enum: EVALUATION_OUTCOMES, description: 'One of "succeeded", "partial", "failed", "abandoned".' },
         note: { type: "string", description: "Optional short reason, up to 400 characters." },
         generation: { type: "number", description: "Optional generation number. Defaults to the current Worker." },
+        workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." },
       }, ["outcome"]),
       handler: function (args) { return handlers.evaluate(args || {}); },
     },