clay-server 4.0.0-beta.2 → 4.0.0-beta.21

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

@@ -2,26 +2,27 @@
 
 var buildShape = require("./session-spawn-mcp-server").buildShape;
 
-function getToolDefs(handlers) {
-  return [
+// `options.lifecycle` adds the autonomous management tools. They are omitted
+// for a plain side-by-side split, which has no Driver role to exercise them.
+function getToolDefs(handlers, options) {
+  var lifecycle = !!(options && options.lifecycle);
+  var defs = [
     {
       name: "send_to_partner",
-      description: "Delegate one concrete task to the visible Split Worker. If this session has no pair yet, Clay creates a real Split Worker session and opens it visibly in the right pane before starting the task. 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.",
+      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." },
         timeoutSeconds: { type: "number", description: "Maximum wait in seconds, from 1 to 900. Defaults to 300." },
-        workerVendor: { type: "string", description: "Optional Split Worker vendor to use only when creating a new pair. Defaults to a suitable installed vendor." },
-        workerModel: { type: "string", description: "Optional Split Worker model to use only when creating a new pair." },
-        workerEffort: { type: "string", description: "Optional Split Worker reasoning effort to use only when creating a new pair." },
+        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." },
       }, ["message"]),
       handler: function (args) { return handlers.send(args || {}); },
     },
     {
       name: "read_partner",
-      description: "Read the partner's current status and recent conversation turns. 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 this for an interim check after a non-waiting delegation or timeout; completed results are pushed automatically.",
       inputSchema: buildShape({
-        lastTurns: { type: "number", description: "Number of recent user-message-delimited turns, from 1 to 5. Defaults to 1." },
+        lastTurns: { type: "number", description: "Number of recent user-message-delimited turns, from 0 to 5. Use 0 for status only. Defaults to 1." },
       }),
       handler: function (args) { return handlers.read(args || {}); },
     },
@@ -38,6 +39,43 @@ function getToolDefs(handlers) {
       handler: function (args) { return handlers.close(args || {}); },
     },
   ];
+  if (!lifecycle) return defs;
+  return defs.concat([
+    {
+      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({}),
+      handler: function (args) { return handlers.status(args || {}); },
+    },
+    {
+      name: "replace_partner",
+      description: "Propose replacing the current Split Worker with a fresh runtime. This non-mutating call shows a user-controlled vendor, model, and effort card. Only acceptance performs the transactional replacement and delegates the supplied task once; decline keeps the existing pair and resumes the Driver. The previous Worker's conversation remains browsable. An active Worker requires interrupt true.",
+      inputSchema: buildShape({
+        interrupt: { type: "boolean", description: "Stop the Worker first if it is mid-turn or holding a delegated task. Required to replace an active Worker." },
+        message: { type: "string", description: "Task to deliver exactly once after the user accepts the replacement." },
+        workerVendor: { type: "string", description: "Optional vendor for the new Worker. Must be installed and available." },
+        workerModel: { type: "string", description: "Optional model for the new Worker. Must be offered by that vendor." },
+        workerEffort: { type: "string", description: "Optional reasoning effort for the new Worker." },
+        recommendationRationale: { type: "string", description: "Concise Driver-authored explanation of why the recommended replacement vendor, model, and effort fit the next task." },
+        evaluation: {
+          type: "object",
+          description: "Optional bounded assessment of the Worker being replaced, recorded against that exact generation.",
+        },
+        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." },
+      }, ["message", "recommendationRationale"]),
+      handler: function (args) { return handlers.replace(args || {}); },
+    },
+    {
+      name: "record_partner_evaluation",
+      description: "Record a bounded assessment of one Split Worker generation so your later model choices can use observed outcomes instead of re-reading transcripts. Records your judgement alongside the objective signals Clay already measured (turns, errors, interruption, context used). This is scoped to your own pair and forms no global model ranking.",
+      inputSchema: buildShape({
+        outcome: { type: "string", 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." },
+      }, ["outcome"]),
+      handler: function (args) { return handlers.evaluate(args || {}); },
+    },
+  ]);
 }
 
 module.exports = { getToolDefs: getToolDefs };

package/lib/session-pair-prompts.js

@@ -0,0 +1,79 @@
+// Driver-facing system prompt text for the visible Driver/Split Worker pair.
+//
+// Pure data, extracted from project-session-pair.js so that module stays under
+// the size limit and so the guidance can be reviewed as prose.
+
+var DRIVER_DELEGATION = [
+  "Your management objective: protect your own context, keep the Split Worker compact, and put execution where",
+  "it runs best. Delegate implementation-heavy work rather than doing it here. Treat work spanning multiple modules,",
+  "crossing client/server/data boundaries, requiring a migration, or containing independent investigation and",
+  "execution as implementation-heavy. Your own capability is not a reason to retain that execution: preserve",
+  "the Driver for decomposition, runtime selection, judgment, review, and integration unless the user explicitly",
+  "asks you to work directly or the work must remain sequential in this session.",
+].join(" ").replace(/ {2,}/g, " ");
+
+var DRIVER_CORE = [
+  "You are the Driver of a visible Driver/Split Worker pair, and you manage that Split Worker yourself.",
+  "The tools send_to_partner, read_partner, partner_status, replace_partner, interrupt_partner, close_partner,",
+  "and record_partner_evaluation are provided directly to you.",
+  "",
+  "Reuse the existing Split Worker",
+  "only when its accumulated context genuinely helps the next task; when it is context-bloated, stale, or",
+  "working on something unrelated, replace it instead of carrying that cost forward. Call partner_status to",
+  "decide: it reports context tokens used and the ratio of its window, current activity, vendor/model/effort,",
+  "history size and idle time, whether replacing is safe right now, and the results you recorded for earlier",
+  "Worker generations. It returns no transcript, so it is cheap to consult. Never tell the user that you will",
+  "reuse the current Worker before checking partner_status. If you previously expected reuse but the status leads",
+  "you to replace it, explicitly say that the decision changed and give the reason.",
+  "",
+  "Use send_to_partner seamlessly for follow-up work in the existing pair. Runtime creation and replacement are",
+  "recorded through a configuration card before anything mutates. replace_partner always posts that card. When",
+  "this Driver is in full-access mode, Clay may auto-accept your exact server-validated recommendation; otherwise",
+  "the selected vendor, model, and effort remain pending until the user explicitly accepts them.",
+  "The replaced Worker keeps its conversation, so nothing is lost. Replacing an actively running Worker requires",
+  "interrupt true, which stops it first only after acceptance. A human Stop",
+  "is authoritative: do not retry, send more work, or replace the Worker in the same turn. Clay blocks those",
+  "actions until the human sends a new Driver message. Use close_partner when they ask to close the pane.",
+  "",
+  "Recommend a Worker vendor, model, and effort from what is actually installed and offered, and include a concise",
+  "rationale explaining why all three fit the task. The card remains visible as an audit trail even when full access",
+  "auto-accepts it; an unavailable choice is never auto-accepted. After a Worker generation finishes or is",
+  "replaced, call record_partner_evaluation with succeeded, partial, failed, or abandoned and a short reason.",
+  "Clay stores that against that exact generation alongside what it measured itself, and partner_status hands it",
+  "back, so your next model choice can use observed results instead of guesswork. This is your own record for",
+  "this pair, not a general ranking of models.",
+  "",
+  "Internal Sub-agents are a distinct execution mechanism, not a lexical category; use them only when the user",
+  "clearly intends internal or background parallel delegation rather than the visible paired session. When",
+  "ambiguous and a visible pair exists, prefer the visible Split Worker. If review or user feedback requires",
+  "corrections to the Split Worker's implementation, delegate a follow-up turn to that Split Worker instead of",
+  "editing its files yourself. If a non-waiting delegation finishes later, Clay pushes the result back and",
+  "resumes you automatically. You also decide the Split Worker's tool-permission requests when they arise;",
+  "approve only what falls inside the task the user authorized. Integrate and verify the final outcome. Do not",
+  "search the project for implementations of these tools, and do not delegate work that must be performed",
+  "sequentially in this same session.",
+].join(" ").replace(/ {2,}/g, " ");
+
+var DRIVER = DRIVER_CORE + " " + DRIVER_DELEGATION;
+
+var UNPAIRED = [
+  "Infer the user's intended target from conversational and UI context. References to a user-visible paired or",
+  "split pane, its session, its activity or status, or a collaborator the user wants opened resolve to Clay's",
+  "Split Worker and its partner tools. Internal Sub-agents are a distinct execution mechanism, not a lexical",
+  "category; use them only when the user clearly intends internal or background parallel delegation rather than a",
+  "visible paired session. When ambiguity would materially change where work runs, ask a concise clarification",
+  "instead of guessing. Treat implementation as heavy when it spans multiple modules, crosses client/server/data",
+  "boundaries, requires a migration, or contains independent investigation and execution. In those cases, call",
+  "propose_worker before substantial execution unless the user explicitly asks you to work directly or the work",
+  "must remain sequential in this session. Your own capability is not a reason to skip delegation: preserve the",
+  "Driver for decomposition, runtime selection, judgment, review, and integration. Give an exact runtime recommendation",
+  "and concise rationale. Clay records and shows the card before the visible pair is accepted or auto-accepted. Do not use a background",
+  "Sub-agent as a substitute for a visible Split Worker.",
+].join(" ").replace(/ {2,}/g, " ");
+
+module.exports = {
+  DRIVER: DRIVER,
+  DRIVER_CORE: DRIVER_CORE,
+  DRIVER_DELEGATION: DRIVER_DELEGATION,
+  UNPAIRED: UNPAIRED,
+};

package/lib/session-pair-turn-control.js

@@ -0,0 +1,153 @@
+// Per-human-turn safety policy for Driver/Split Worker orchestration.
+//
+// A human Stop is a cancellation barrier, not merely an AbortController
+// signal. It blocks delegation and Worker replacement until the next ordinary
+// human message reaches the Driver. Internal result and permission messages do
+// not clear it. Creation budgets and operation ids also make retries bounded
+// and idempotent even when no Stop occurred.
+
+var MAX_CREATIONS_PER_TURN = 2;
+var MAX_REPLACEMENTS_PER_TURN = 1;
+var MAX_OPERATION_ID_CHARS = 120;
+
+function attachPairTurnControl(ctx) {
+  var sm = ctx.sm;
+  var store = ctx.splitStore;
+
+  function stateFor(driver) {
+    if (!driver._pairTurnControl) {
+      driver._pairTurnControl = {
+        serial: 0,
+        humanStopped: false,
+        stoppedAt: null,
+        stoppedWorkerId: null,
+        creations: 0,
+        replacements: 0,
+        operations: Object.create(null),
+      };
+    }
+    return driver._pairTurnControl;
+  }
+
+  function liveSession(session) {
+    return !!(session && sm.sessions.get(session.localId) === session);
+  }
+
+  function rolesFor(session) {
+    if (!liveSession(session)) return null;
+    var group = store.groupForMember(session.localId);
+    if (!group || !group.pair) return null;
+    var driver = sm.sessions.get(group.pair.driverId);
+    var worker = sm.sessions.get(group.pair.workerId);
+    if (!liveSession(driver) || !liveSession(worker)) return null;
+    if ((driver.ownerId || null) !== (worker.ownerId || null)) return null;
+    return { group: group, driver: driver, worker: worker };
+  }
+
+  function beginHumanTurn(session) {
+    if (!liveSession(session)) return false;
+    var roles = rolesFor(session);
+    var driver = roles ? roles.driver : session;
+    if (roles && roles.driver !== session) return false;
+    var state = stateFor(driver);
+    state.serial += 1;
+    state.humanStopped = false;
+    state.stoppedAt = null;
+    state.stoppedWorkerId = null;
+    state.creations = 0;
+    state.replacements = 0;
+    state.operations = Object.create(null);
+    return true;
+  }
+
+  function markHumanStop(session) {
+    var roles = rolesFor(session);
+    if (!roles) return null;
+    var state = stateFor(roles.driver);
+    state.humanStopped = true;
+    state.stoppedAt = Date.now();
+    state.stoppedWorkerId = roles.worker.localId;
+    return roles;
+  }
+
+  function blockedReason(driver) {
+    if (!liveSession(driver)) return "this Driver session is no longer live";
+    var state = stateFor(driver);
+    if (!state.humanStopped) return null;
+    return "the human stopped this Split Worker turn; Worker actions are blocked until the human sends a new message to the Driver";
+  }
+
+  function assertWorkerAction(driver) {
+    var reason = blockedReason(driver);
+    if (reason) throw new Error(reason);
+  }
+
+  function reserveCreation(driver, kind) {
+    assertWorkerAction(driver);
+    var state = stateFor(driver);
+    if (kind === "replace" && state.replacements >= MAX_REPLACEMENTS_PER_TURN) {
+      throw new Error("the Split Worker replacement limit for this human turn has been reached; wait for a new human message before replacing it again");
+    }
+    if (state.creations >= MAX_CREATIONS_PER_TURN) {
+      throw new Error("the Split Worker creation limit for this human turn has been reached; wait for a new human message before creating another Worker");
+    }
+    state.creations += 1;
+    if (kind === "replace") state.replacements += 1;
+    return { driver: driver, kind: kind, active: true };
+  }
+
+  function releaseCreation(ticket) {
+    if (!ticket || !ticket.active || !liveSession(ticket.driver)) return;
+    ticket.active = false;
+    var state = stateFor(ticket.driver);
+    state.creations = Math.max(0, state.creations - 1);
+    if (ticket.kind === "replace") state.replacements = Math.max(0, state.replacements - 1);
+  }
+
+  function operationId(value) {
+    if (typeof value !== "string") return "";
+    var clean = value.trim();
+    if (!clean || clean.length > MAX_OPERATION_ID_CHARS || !/^[A-Za-z0-9._:-]+$/.test(clean)) return "";
+    return clean;
+  }
+
+  function runOperation(driver, kind, rawId, fn) {
+    var id = operationId(rawId);
+    if (!id) return Promise.resolve().then(fn);
+    var state = stateFor(driver);
+    var key = kind + ":" + id;
+    if (state.operations[key]) return state.operations[key];
+    var promise = Promise.resolve().then(fn);
+    state.operations[key] = promise;
+    return promise;
+  }
+
+  function status(driver) {
+    var state = stateFor(driver);
+    return {
+      humanStopped: state.humanStopped,
+      stoppedAt: state.stoppedAt,
+      stoppedWorkerId: state.stoppedWorkerId,
+      turnSerial: state.serial,
+      creationsThisTurn: state.creations,
+      replacementsThisTurn: state.replacements,
+    };
+  }
+
+  return {
+    assertWorkerAction: assertWorkerAction,
+    beginHumanTurn: beginHumanTurn,
+    blockedReason: blockedReason,
+    markHumanStop: markHumanStop,
+    releaseCreation: releaseCreation,
+    reserveCreation: reserveCreation,
+    runOperation: runOperation,
+    status: status,
+  };
+}
+
+module.exports = {
+  MAX_CREATIONS_PER_TURN: MAX_CREATIONS_PER_TURN,
+  MAX_REPLACEMENTS_PER_TURN: MAX_REPLACEMENTS_PER_TURN,
+  attachPairTurnControl: attachPairTurnControl,
+};

package/lib/session-provenance.js

@@ -0,0 +1,119 @@
+var crypto = require("crypto");
+
+var PROVENANCE_VERSION = 1;
+var MAX_ORIGIN_LENGTH = 128;
+
+function safeOriginId(value) {
+  if (typeof value !== "string") return null;
+  var trimmed = value.trim();
+  if (!trimmed || trimmed.length > MAX_ORIGIN_LENGTH) return null;
+  return trimmed;
+}
+
+function ensureOrigin(session) {
+  if (!session) return null;
+  var existing = safeOriginId(session.sessionOriginId);
+  if (existing) {
+    session.sessionOriginId = existing;
+    return existing;
+  }
+  session.sessionOriginId = crypto.randomUUID();
+  return session.sessionOriginId;
+}
+
+function isWorker(session) {
+  return !!(session && session.sessionProvenance && session.sessionProvenance.kind === "worker");
+}
+
+function nextWorkerGeneration(parentOriginId, sessions) {
+  var next = 1;
+  sessions.forEach(function (session) {
+    var provenance = session && session.sessionProvenance;
+    if (!provenance || provenance.kind !== "worker" || provenance.parentSessionOriginId !== parentOriginId) return;
+    var generation = Number.isInteger(provenance.generation) && provenance.generation > 0 ? provenance.generation : 0;
+    if (generation >= next) next = generation + 1;
+  });
+  return next;
+}
+
+function markWorker(driver, worker, sessions) {
+  if (!driver || !worker || driver === worker) throw new Error("Split Worker provenance requires distinct sessions");
+  if ((driver.ownerId || null) !== (worker.ownerId || null)) throw new Error("Split Worker provenance requires the same owner");
+  if (isWorker(driver)) throw new Error("A Split Worker cannot become a Driver");
+  var parentOriginId = ensureOrigin(driver);
+  ensureOrigin(worker);
+  worker.sessionProvenance = {
+    version: PROVENANCE_VERSION,
+    kind: "worker",
+    parentSessionOriginId: parentOriginId,
+    generation: nextWorkerGeneration(parentOriginId, sessions),
+    createdVia: "split-worker",
+    createdAt: Date.now(),
+  };
+  return worker.sessionProvenance;
+}
+
+function restore(meta, session) {
+  var storedOriginId = safeOriginId(meta && meta.sessionOriginId);
+  ensureOrigin(session);
+  var stored = meta && meta.sessionProvenance;
+  if (!stored || stored.kind !== "worker") return storedOriginId !== session.sessionOriginId;
+  var parentOriginId = safeOriginId(stored.parentSessionOriginId);
+  // A corrupt Worker record remains a Worker. It is projected as orphaned
+  // instead of silently gaining top-level Driver authority.
+  session.sessionProvenance = {
+    version: PROVENANCE_VERSION,
+    kind: "worker",
+    parentSessionOriginId: parentOriginId,
+    generation: Number.isInteger(stored.generation) && stored.generation > 0 ? stored.generation : null,
+    createdVia: stored.createdVia === "split-worker" ? "split-worker" : null,
+    createdAt: typeof stored.createdAt === "number" && isFinite(stored.createdAt) ? stored.createdAt : null,
+  };
+  return storedOriginId !== session.sessionOriginId || JSON.stringify(stored) !== JSON.stringify(session.sessionProvenance);
+}
+
+function metadata(session) {
+  var result = { sessionOriginId: ensureOrigin(session) };
+  if (isWorker(session)) result.sessionProvenance = Object.assign({}, session.sessionProvenance);
+  return result;
+}
+
+function hierarchyFor(sessions) {
+  var originMap = {};
+  var duplicateOrigins = {};
+  for (var i = 0; i < sessions.length; i++) {
+    var originId = safeOriginId(sessions[i] && sessions[i].sessionOriginId);
+    if (!originId) continue;
+    if (originMap[originId]) duplicateOrigins[originId] = true;
+    else originMap[originId] = sessions[i];
+  }
+  var result = {};
+  for (var j = 0; j < sessions.length; j++) {
+    var session = sessions[j];
+    if (!isWorker(session)) {
+      result[session.localId] = { role: "driver", parentSessionId: null, parentAvailable: false, generation: null };
+      continue;
+    }
+    var provenance = session.sessionProvenance;
+    var parentOriginId = safeOriginId(provenance.parentSessionOriginId);
+    var parent = duplicateOrigins[parentOriginId] ? null : originMap[parentOriginId];
+    var sameOwner = parent && (parent.ownerId || null) === (session.ownerId || null);
+    var validParent = sameOwner && !isWorker(parent) ? parent : null;
+    result[session.localId] = {
+      role: "worker",
+      parentSessionId: validParent ? validParent.localId : null,
+      parentAvailable: !!validParent,
+      generation: Number.isInteger(provenance.generation) && provenance.generation > 0 ? provenance.generation : null,
+    };
+  }
+  return result;
+}
+
+module.exports = {
+  ensureOrigin: ensureOrigin,
+  hierarchyFor: hierarchyFor,
+  isWorker: isWorker,
+  markWorker: markWorker,
+  metadata: metadata,
+  restore: restore,
+};

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

@@ -27,7 +27,7 @@ function getToolDefs(handlers) {
   return [
     {
       name: "spawn_sessions",
-      description: "Create sibling work sessions in this project. Set forkFromCurrent to copy this session's full conversation context into every child. Children share the project's working directory, so prefer parallel analysis or other non-conflicting work over concurrent edits. Results can be polled with check_spawned_sessions; spawned children cannot spawn further sessions.",
+      description: "Create ordinary sibling work sessions for background parallel work. This does not create a visible Driver/Split Worker pair and must not be used when the user asks for a Worker, paired pane, or split collaborator; use send_to_partner for that. Set forkFromCurrent to copy this session's full conversation context into every child. Children share the project's working directory, so prefer parallel analysis or other non-conflicting work over concurrent edits. Results can be polled with check_spawned_sessions; spawned children cannot spawn further sessions.",
       inputSchema: buildShape({
         sessions: { type: "string", description: "JSON array of objects: [{\"title\":\"Task title\",\"prompt\":\"Task instructions\"}]" },
         vendor: { type: "string", description: "Optional vendor id. Defaults to the parent session vendor, then the project default." },

package/lib/session-split-groups.js

@@ -280,7 +280,10 @@ function attachSplitGroups(ctx) {
   });
 
   function sendState(ws) {
-    if (!ws || ws._clayPane) return;
+    if (!ws) return;
+    // Pane clients need the same owner-scoped pair roles as the parent shell.
+    // The Worker composer lock resolves its role from this projection; hiding
+    // the projection from panes leaves a configured Worker looking editable.
     ctx.sendTo(ws, { type: "split_groups", groups: store.listFor(ws) });
   }
 

package/lib/session-title-policy.js

@@ -0,0 +1,60 @@
+// Session title policy shared by query startup and completed-turn processing.
+// Initial titles are immediate, provisional UI labels. Model-generated titles
+// replace them after enough conversation exists to describe the actual topic.
+
+var DEFAULT_GENERATION_TURN = 2;
+var HOME_GENERATION_TURN = 1;
+var MAX_PROVISIONAL_CHARS = 60;
+var LEGACY_SEARCH_TITLE = "This conversation began in Clay Studio's global search.";
+
+function cleanText(value) {
+  if (typeof value !== "string") return "";
+  return value.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
+}
+
+function firstRecordedUserMessage(session) {
+  var history = session && Array.isArray(session.history) ? session.history : [];
+  for (var i = 0; i < history.length; i++) {
+    if (history[i] && history[i].type === "user_message") {
+      var text = cleanText(history[i].text);
+      if (text) return text;
+    }
+  }
+  return "";
+}
+
+function selectInitialTitle(session, transportText) {
+  var existing = cleanText(session && session.title);
+  if (existing) return { title: existing, provisional: false };
+
+  // Prefer the visible message recorded in history. Query transports may wrap
+  // it in identical provider instructions, as global Ask Clay does.
+  var source = firstRecordedUserMessage(session) || cleanText(transportText);
+  if (source.length < 10) return { title: null, provisional: false };
+  return {
+    title: source.length > MAX_PROVISIONAL_CHARS ? source.substring(0, MAX_PROVISIONAL_CHARS) : source,
+    provisional: true,
+  };
+}
+
+function generationTurn(isMate) {
+  return isMate === true ? HOME_GENERATION_TURN : DEFAULT_GENERATION_TURN;
+}
+
+function repairLegacySearchTitle(session) {
+  var title = cleanText(session && session.title);
+  if (!session || title.indexOf(LEGACY_SEARCH_TITLE) !== 0) return false;
+  var source = firstRecordedUserMessage(session);
+  if (!source) return false;
+  session.title = source.length > MAX_PROVISIONAL_CHARS ? source.substring(0, MAX_PROVISIONAL_CHARS) : source;
+  session.titleAutoGenerated = false;
+  return true;
+}
+
+module.exports = {
+  DEFAULT_GENERATION_TURN: DEFAULT_GENERATION_TURN,
+  HOME_GENERATION_TURN: HOME_GENERATION_TURN,
+  selectInitialTitle: selectInitialTitle,
+  generationTurn: generationTurn,
+  repairLegacySearchTitle: repairLegacySearchTitle,
+};

package/lib/session-visibility.js

@@ -0,0 +1,39 @@
+function normalize(value) {
+  return value === "shared" ? "shared" : "private";
+}
+
+function restore(meta) {
+  // Older releases persisted the shared default without recording intent.
+  return meta.sessionVisibilityExplicit === true ? normalize(meta.sessionVisibility) : "private";
+}
+
+function handleChange(ctx, ws, msg) {
+  if (typeof msg.sessionId !== "number" || (msg.visibility !== "shared" && msg.visibility !== "private")) return;
+  var session = ctx.sm.sessions.get(msg.sessionId);
+  if (!session) return;
+  if (ctx.usersModule.isMultiUser()) {
+    var user = ws._clayUser;
+    var project = ctx.getProjectAccess ? ctx.getProjectAccess() : { visibility: "public" };
+    if (!user || !session.ownerId || session.ownerId !== user.id ||
+        !ctx.usersModule.canAccessSession(user.id, session, project)) return;
+  } else if (session.ownerId) {
+    return;
+  }
+  ctx.sm.setSessionVisibility(msg.sessionId, msg.visibility);
+  revokeViewers(ctx, session);
+}
+
+function revokeViewers(ctx, session) {
+  if (ctx.usersModule.isMultiUser() && session.sessionVisibility === "private") {
+    ctx.clients.forEach(function(client) {
+      if (client._clayActiveSession !== session.localId) return;
+      if (client._clayUser && client._clayUser.id === session.ownerId) return;
+      // 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");
+    });
+  }
+}
+
+module.exports = { normalize: normalize, restore: restore, handleChange: handleChange, revokeViewers: revokeViewers };