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

package/lib/session-pair-factory.js

@@ -0,0 +1,233 @@
+// Split-group pair creation.
+//
+// Extracted from project-session-pair.js, which operates a pair once it
+// exists; this module is only about how one comes into being. Both the
+// explicit "Add Split Worker" flow and the Driver-initiated
+// send_to_partner-creates-a-pair flow land here, so vendor validation, owner
+// derivation and the group record are written in exactly one place.
+//
+// Ownership always comes from the connection or the Driver session, never from
+// the incoming message.
+//
+// Two ordering rules matter and are load-bearing:
+//
+//   1. Nothing is created until everything is validated. Driver eligibility and
+//      both runtime requests are settled first, so a rejected request leaves no
+//      orphan session behind. For a newly requested Driver the tier is checked
+//      against the model that session would actually resolve to, before either
+//      session exists.
+//   2. `preflightRuntime` is side-effect free, so a caller that is about to
+//      destroy something (replacement dissolving a live pair) can validate the
+//      replacement first and abort while the old pair is still intact.
+
+var driverEligibility = require("./session-driver-eligibility");
+var models = require("./project-models");
+var yoke = require("./yoke");
+
+function attachPairFactory(ctx) {
+  var sm = ctx.sm;
+  var store = ctx.splitStore;
+
+  function validateVendor(vendor) {
+    var installed = sm.installedVendors || [];
+    if (!vendor || installed.indexOf(vendor) === -1) throw new Error("vendor is not installed: " + (vendor || "unknown"));
+    return vendor;
+  }
+
+  // An explicitly requested model must exist in the server's own catalog for
+  // that vendor, matched through the repo's canonical matcher so an alias, an
+  // id or a resolvedModel all count. Caller text is never taken on trust: if
+  // the catalog is not populated we cannot confirm the model, so an explicit
+  // request fails closed rather than being forwarded blindly.
+  function validateModel(vendor, model) {
+    var requested = typeof model === "string" ? model.trim() : "";
+    if (!requested) return null;
+    var catalog = (sm.modelsByVendor && sm.modelsByVendor[vendor]) || [];
+    if (catalog.length === 0) {
+      throw new Error("no models are available yet for vendor \"" + vendor +
+        "\", so model \"" + requested + "\" cannot be confirmed");
+    }
+    for (var i = 0; i < catalog.length; i++) {
+      if (models.modelEntryMatches(catalog[i], requested)) return requested;
+    }
+    throw new Error("model is not available for vendor \"" + vendor + "\": " + requested);
+  }
+
+  function validateEffort(vendor, effort) {
+    var requested = typeof effort === "string" ? effort.trim() : "";
+    var fallback = (sm.currentEffortByVendor && sm.currentEffortByVendor[vendor]) || sm.currentEffort || "medium";
+    var clamped = yoke.clampEffort(vendor, requested || fallback) || null;
+    if (requested && !clamped) {
+      throw new Error("reasoning effort is not supported for vendor \"" + vendor + "\": " + requested);
+    }
+    return clamped;
+  }
+
+  // Resolve and validate one session runtime request without creating
+  // anything. Throws on the first unusable field.
+  function preflightRuntime(spec, defaultVendor) {
+    var request = spec || {};
+    var vendor = validateVendor((typeof request.vendor === "string" && request.vendor.trim()) || defaultVendor);
+    return {
+      vendor: vendor,
+      model: validateModel(vendor, request.model),
+      effort: validateEffort(vendor, request.effort),
+      explicitEffort: !!(typeof request.effort === "string" && request.effort.trim()),
+    };
+  }
+
+  // The vendor a Driver-initiated Worker gets when none is named: prefer a
+  // different engine from the Driver's own, so the pair does not double up.
+  function defaultWorkerVendorFor(driver) {
+    var installed = sm.installedVendors || [];
+    if (installed.length === 0) throw new Error("no coding agent is installed for a Split Worker session");
+    if (installed.indexOf("codex") !== -1 && driver.vendor !== "codex") return "codex";
+    for (var i = 0; i < installed.length; i++) {
+      if (installed[i] !== driver.vendor) return installed[i];
+    }
+    return installed[0];
+  }
+
+  // Side-effect-free check that this exact Driver could create this exact
+  // Worker right now. Used by replacement before it touches anything.
+  function preflightWorkerForDriver(driver, args) {
+    if (ctx.isMate) throw new Error("Pair sessions are only available in projects");
+    if (!driver) throw new Error("driver session not found");
+    var verdict = driverEligibility.evaluateDriverSession(driver, sm);
+    if (!verdict.ok) throw new Error(verdict.error);
+    var options = args || {};
+    var vendor = typeof options.workerVendor === "string" ? options.workerVendor.trim() : "";
+    return preflightRuntime({
+      vendor: vendor || defaultWorkerVendorFor(driver),
+      model: options.workerModel,
+      effort: options.workerEffort,
+    }, null);
+  }
+
+  function createPairRecord(ws, msg) {
+    if (ctx.isMate) throw new Error("Pair sessions are only available in projects");
+    var driverSpec = msg.driver || {};
+    var workerSpec = msg.worker || {};
+    var ownerId = ws._clayUser && ctx.usersModule.isMultiUser() ? ws._clayUser.id : null;
+
+    // --- Validate everything first; create nothing yet. ---
+
+    var workerRuntime = preflightRuntime(workerSpec, sm.lastVendor || "codex");
+
+    var existingDriver = null;
+    var driverRuntime = null;
+    var groupName;
+    if (Number.isInteger(driverSpec.sessionId)) {
+      // "Add Split Worker" on an existing session: the current session becomes
+      // the Driver with its full conversation context intact.
+      existingDriver = sm.sessions.get(driverSpec.sessionId);
+      if (!existingDriver) throw new Error("driver session not found");
+      if ((existingDriver.ownerId || null) !== ownerId) throw new Error("driver session access denied");
+      if (store.groupForMember(existingDriver.localId)) throw new Error("this session is already in a split group");
+      var existingVerdict = driverEligibility.evaluateDriverSession(existingDriver, sm);
+      if (!existingVerdict.ok) throw new Error(existingVerdict.error);
+      groupName = undefined; // auto name from member titles
+    } else {
+      driverRuntime = preflightRuntime(driverSpec, "claude");
+      // The tier is judged on the model this session would really resolve to:
+      // the explicit request if there is one, else that vendor's default.
+      var effectiveDriverModel = driverRuntime.model ||
+        (sm.defaultModelByVendor && sm.defaultModelByVendor[driverRuntime.vendor]) || "";
+      var newVerdict = driverEligibility.evaluateDriverModel(
+        driverRuntime.vendor, effectiveDriverModel, sm.modelsByVendor
+      );
+      if (!newVerdict.ok) throw new Error(newVerdict.error);
+      groupName = "Agent pair";
+    }
+
+    // --- Everything is valid; now create. ---
+
+    var driver = existingDriver;
+    var createdDriver = null;
+    if (!driver) {
+      driver = sm.createSessionRaw({
+        ownerId: ownerId,
+        vendor: driverRuntime.vendor,
+        model: driverRuntime.model,
+        effort: driverRuntime.effort,
+      });
+      createdDriver = driver;
+      driver.title = "Driver · " + ((yoke.getVendorInfo(driverRuntime.vendor) || {}).displayName || driverRuntime.vendor);
+      if (driverRuntime.explicitEffort) driver.loopSettings = { effort: driverRuntime.effort };
+    }
+
+    var worker = sm.createSessionRaw({
+      ownerId: ownerId,
+      vendor: workerRuntime.vendor,
+      model: workerRuntime.model,
+      effort: workerRuntime.effort,
+    });
+    worker.title = "Split Worker · " + ((yoke.getVendorInfo(workerRuntime.vendor) || {}).displayName || workerRuntime.vendor);
+    if (workerRuntime.explicitEffort) worker.loopSettings = { effort: workerRuntime.effort };
+
+    var result = store.create(ws, {
+      members: [driver.localId, worker.localId],
+      pair: { driverId: driver.localId, workerId: worker.localId },
+      name: groupName,
+    });
+    if (!result.ok) {
+      // The group is the last step, so a failure here would otherwise strand
+      // the sessions this call just made. Only sessions created by this call
+      // are removed; an existing Driver is never touched.
+      removeCreated(worker);
+      removeCreated(createdDriver);
+      throw new Error(result.error);
+    }
+    sm.broadcastSessionList();
+    return { driver: driver, worker: worker, group: result.group };
+  }
+
+  function removeCreated(session) {
+    if (!session) return;
+    if (typeof sm.deleteSessionQuiet === "function") {
+      try { sm.deleteSessionQuiet(session.localId); return; } catch (e) {}
+    }
+    try { sm.sessions.delete(session.localId); } catch (e) {}
+  }
+
+  function createWorkerForDriver(driver, args) {
+    // Validates the Driver's eligibility and the whole Worker runtime before
+    // any session is made, so a rejection creates nothing.
+    var runtime = preflightWorkerForDriver(driver, args);
+    var ws = {
+      _clayActiveSession: driver.localId,
+      _clayUser: driver.ownerId ? { id: driver.ownerId } : null,
+    };
+    var created = createPairRecord(ws, {
+      driver: { sessionId: driver.localId },
+      worker: {
+        vendor: runtime.vendor,
+        model: runtime.model || "",
+        effort: runtime.explicitEffort ? (args && args.workerEffort) || "" : "",
+      },
+    });
+    sm.sendToSession(driver, { type: "pair_session_created", ok: true, group: created.group });
+    return created;
+  }
+
+  function createPair(ws, msg) {
+    try {
+      var created = createPairRecord(ws, msg);
+      ctx.sendTo(ws, { type: "pair_session_created", ok: true, group: created.group });
+    } catch (e) {
+      ctx.sendTo(ws, { type: "pair_session_created", ok: false, error: e.message || String(e) });
+    }
+  }
+
+  return {
+    createPair: createPair,
+    createPairRecord: createPairRecord,
+    createWorkerForDriver: createWorkerForDriver,
+    preflightRuntime: preflightRuntime,
+    preflightWorkerForDriver: preflightWorkerForDriver,
+    validateModel: validateModel,
+    validateVendor: validateVendor,
+  };
+}
+
+module.exports = { attachPairFactory: attachPairFactory };

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

@@ -2,11 +2,14 @@
 
 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 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 — no approval step and no suggestion card. 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." },
@@ -19,9 +22,9 @@ function getToolDefs(handlers) {
     },
     {
       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 +41,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: "Replace your Split Worker with a fresh, compact one in a single operation: the old pair is dissolved, a new Worker session is created and opened visibly, and an optional task is delivered to it. The previous Worker's conversation is preserved and stays browsable. Use this when the current Worker is context-bloated, stale, or working on something unrelated to the next task. Refuses while the Worker is mid-turn unless you pass 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: "Optional task to deliver to the new Worker immediately after it is created." },
+        wait: { type: "boolean", description: "When a message is given, wait for that 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 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." },
+        evaluation: {
+          type: "object",
+          description: "Optional bounded assessment of the Worker being replaced, recorded against that exact generation.",
+        },
+      }),
+      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,60 @@
+// 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. There is no
+// proposal or approval language here by design: a qualified Driver manages its
+// Worker on its own authority, so telling the model to suggest or ask would
+// contradict the tools it actually has.
+
+var DRIVER = [
+  "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.",
+  "",
+  "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. 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.",
+  "",
+  "Act on your own authority. You create, reuse, interrupt, replace, and close the Split Worker without asking",
+  "the user and without posting any suggestion or approval card. send_to_partner creates and opens a visible",
+  "Split Worker when none exists. replace_partner dissolves the current pair and opens a fresh compact Worker in",
+  "one step, optionally delivering the next task with it; the replaced Worker keeps its conversation, so nothing",
+  "is lost. Replacing an actively running Worker requires interrupt true, which stops it first. The human may",
+  "still message or stop the Split Worker directly; treat that intervention as authoritative, and use",
+  "close_partner immediately when they ask to close or dismiss the pane.",
+  "",
+  "Choose the Worker vendor, model, and effort for the task from what is actually installed and offered; an",
+  "unavailable choice is refused rather than silently substituted. 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 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. When a task is implementation-heavy, call send_to_partner directly: Clay creates the",
+  "paired Split Worker session and opens it in the right pane automatically before delivering the task. Do not",
+  "ask the user for permission to start one, do not ask them to enable split mode, and do not use a background",
+  "Sub-agent as a substitute for a visible Split Worker.",
+].join(" ").replace(/ {2,}/g, " ");
+
+module.exports = { DRIVER: DRIVER, UNPAIRED: UNPAIRED };

package/lib/sessions.js

@@ -5,6 +5,7 @@ var utils = require("./utils");
 var users = require("./users");
 var { CODEX_DEFAULTS } = require("./codex-defaults");
 var hygiene = require("./session-hygiene");
+var backgroundTaskTiming = require("./background-task-timing");
 
 function createSessionManager(opts) {
   var cwd = opts.cwd;
@@ -508,7 +509,9 @@ function createSessionManager(opts) {
       title: s.title || "New Session",
       active: isActive,
       isProcessing: s.isProcessing,
-      backgroundTaskCount: (s.activeBackgroundTasks || []).length,
+      // Sidebar badge: user work only. Ambient housekeeping is surfaced in the
+      // composer's expanded list, never as a count demanding attention.
+      backgroundTaskCount: backgroundTaskTiming.countUserTasks(s.activeBackgroundTasks),
       lastActivity: s.lastActivity || s.createdAt || 0,
       loop: loop,
       spawn: s.spawn || null,

package/lib/tools-registry.js

@@ -137,7 +137,17 @@ function seedBuiltInCapsules(ctx) {
   for (var ri = 0; ri < REMOVED_BUILTIN_IDS.length; ri++) {
     fs.rmSync(path.join(root, REMOVED_BUILTIN_IDS[ri]), { recursive: true, force: true });
   }
-  var entries = fs.readdirSync(CAPSULES_ROOT, { withFileTypes: true });
+  // Clay ships no built-in Capsules any more, so lib/capsules/ is absent from a
+  // fresh checkout and from the npm tarball (neither git nor npm carries an
+  // empty directory). Seeding still owns the removed-built-in migration above
+  // and the marker below, so an absent root means "nothing to copy" rather than
+  // a failure. Anything other than a missing root is still a real error.
+  var entries = [];
+  try {
+    entries = fs.readdirSync(CAPSULES_ROOT, { withFileTypes: true });
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
   var seeded = [];
   for (var i = 0; i < entries.length; i++) {
     if (!entries[i].isDirectory()) continue;