clay-server 4.0.0-beta.13 → 4.0.0-beta.15

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/sessions.js

@@ -6,6 +6,7 @@ var users = require("./users");
 var { CODEX_DEFAULTS } = require("./codex-defaults");
 var hygiene = require("./session-hygiene");
 var backgroundTaskTiming = require("./background-task-timing");
+var sessionProvenance = require("./session-provenance");
 
 function createSessionManager(opts) {
   var cwd = opts.cwd;
@@ -180,6 +181,9 @@ function createSessionManager(opts) {
       if (session.homeDebateInitialTopic) metaObj.homeDebateInitialTopic = session.homeDebateInitialTopic;
       if (session.homeClayEntryRequestId) metaObj.homeClayEntryRequestId = session.homeClayEntryRequestId;
       if (session.homeClayEntryMode) metaObj.homeClayEntryMode = session.homeClayEntryMode;
+      var provenanceMeta = sessionProvenance.metadata(session);
+      metaObj.sessionOriginId = provenanceMeta.sessionOriginId;
+      if (provenanceMeta.sessionProvenance) metaObj.sessionProvenance = provenanceMeta.sessionProvenance;
       var meta = JSON.stringify(metaObj);
       var lines = [meta];
       for (var i = 0; i < session.history.length; i++) {
@@ -300,6 +304,8 @@ function createSessionManager(opts) {
       if (m.homeClayEntryRequestId) session.homeClayEntryRequestId = m.homeClayEntryRequestId;
       if (m.homeClayEntryMode) session.homeClayEntryMode = m.homeClayEntryMode;
       if (m.ownerId) session.ownerId = m.ownerId;
+      session.sessionOriginId = m.sessionOriginId || null;
+      session._provenanceMigrationNeeded = sessionProvenance.restore(m, session);
       // Born-TUI session: PTY is gone after restart, but the cliSessionId
       // is still resumable via `claude --resume <id>`. We mark the mode
       // here so it shows up in the sidebar with the right icon; the
@@ -320,6 +326,20 @@ function createSessionManager(opts) {
       session.favoriteOrder = typeof m.favoriteOrder === "number" ? m.favoriteOrder : null;
       sessions.set(localId, session);
     }
+
+    // Versionless legacy records are safe top-level Drivers. Assigning an
+    // opaque origin ID is the only migration: no title, slug or active split
+    // state is used to invent historical parentage.
+    sessions.forEach(function (session) {
+      if (!session.cliSessionId || !session._provenanceMigrationNeeded) return;
+      var activityTime = session.lastActivity;
+      saveSessionFile(session);
+      try {
+        var preservedTime = new Date(activityTime);
+        fs.utimesSync(sessionFilePath(session.cliSessionId), preservedTime, preservedTime);
+      } catch (e) {}
+      delete session._provenanceMigrationNeeded;
+    });
   }
 
   // Adopt orphaned CLI sessions from ~/.claude/projects/<encoded-cwd>/ as
@@ -532,6 +552,19 @@ function createSessionManager(opts) {
     };
   }
 
+  function mapSessionsForClient(source, clientActiveId, wsUnread) {
+    var hierarchy = sessionProvenance.hierarchyFor(source);
+    return source.map(function (session) {
+      var mapped = mapSessionForClient(session, clientActiveId, wsUnread);
+      var node = hierarchy[session.localId];
+      mapped.sessionRole = node.role;
+      mapped.parentSessionId = node.parentSessionId;
+      mapped.parentAvailable = node.parentAvailable;
+      mapped.workerGeneration = node.generation;
+      return mapped;
+    });
+  }
+
   function getVisibleSessions() {
     var multiUser = users.isMultiUser();
     return [...sessions.values()].filter(function (s) {
@@ -554,14 +587,14 @@ function createSessionManager(opts) {
         if (ws.readyState === 1) {
           ws.send(JSON.stringify({
             type: "session_list",
-            sessions: filtered.map(function (s) { return mapSessionForClient(s, clientActiveId, wsUnread); }),
+            sessions: mapSessionsForClient(filtered, clientActiveId, wsUnread),
           }));
         }
       });
     } else {
       send({
         type: "session_list",
-        sessions: allVisible.map(function (s) { return mapSessionForClient(s); }),
+        sessions: mapSessionsForClient(allVisible),
       });
     }
   }
@@ -598,7 +631,9 @@ function createSessionManager(opts) {
       permissionMode: (sessionOpts && sessionOpts.permissionMode) || null,
       permissionModeBeforeFullAccess: null,
       terminalId: null,
+      sessionOriginId: null,
     };
+    sessionProvenance.ensureOrigin(session);
     sessions.set(localId, session);
     switchSession(localId, targetWs);
     return session;
@@ -637,7 +672,9 @@ function createSessionManager(opts) {
       permissionMode: (sessionOpts && sessionOpts.permissionMode) || null,
       permissionModeBeforeFullAccess: null,
       terminalId: null,
+      sessionOriginId: null,
     };
+    sessionProvenance.ensureOrigin(session);
     sessions.set(localId, session);
     return session;
   }
@@ -1248,6 +1285,7 @@ function createSessionManager(opts) {
     searchSessionContent: searchSessionContent,
     setResolveLoopInfo: setResolveLoopInfo,
     mapSessionForClient: mapSessionForClient,
+    mapSessionsForClient: mapSessionsForClient,
     migrateSessionTitles: migrateSessionTitles,
     setSessionVisibility: function (localId, visibility) {
       var session = sessions.get(localId);

package/lib/tools-registry.js

@@ -3,9 +3,10 @@ var path = require("path");
 var config = require("./config");
 var toolUiSpec = require("./tool-ui-spec");
 var toolCapsuleSource = require("./tool-capsule-source");
+var capsuleFloor = require("./capsule-display-floor");
 
 var CAPSULES_ROOT = path.join(__dirname, "capsules");
-var SEED_MARKER = ".capsules-v7";
+var SEED_MARKER = ".capsules-v9";
 var REMOVED_BUILTIN_IDS = ["board", "translator", "scratchpad"];
 var UI_NODE_TYPES = toolUiSpec.UI_NODE_TYPES;
 var DISCOVERY_FIELD_MAX_LENGTH = 240;
@@ -98,6 +99,11 @@ function validateManifest(manifest, opts) {
   if (manifest.skills !== undefined && typeof manifest.skills !== "string") {
     throw new Error("Tool skills must be markdown text.");
   }
+  // The floor gate always validates the Display itself, so a manifest may
+  // never carry a claim about it.
+  if (manifest.displayFloor !== undefined) {
+    throw new Error("Tool displayFloor cannot be authored; Clay validates the Display itself.");
+  }
   validateDiscoveryField(manifest, "description", "description");
   validateDiscoveryField(manifest, "useWhen", "useWhen");
   if (manifest.permissions !== undefined) {
@@ -129,19 +135,31 @@ function toolDirectory(ctx, id) {
   return path.join(resolveToolsRoot(ctx), id);
 }
 
+function hasAnySeedMarker(root) {
+  try {
+    return fs.readdirSync(root).some(function (name) { return /^\.capsules-v\d+$/.test(name); });
+  } catch (e) {
+    return false;
+  }
+}
+
 function seedBuiltInCapsules(ctx) {
   var root = resolveToolsRoot(ctx);
   var marker = path.join(root, SEED_MARKER);
   if (fs.existsSync(marker)) return;
+  // The removed-built-in cleanup is a one-time migration. Any earlier marker
+  // means it already ran, so a later marker bump must not delete a Capsule the
+  // user has since authored under one of those IDs.
+  var migrated = hasAnySeedMarker(root);
   fs.mkdirSync(root, { recursive: true });
-  for (var ri = 0; ri < REMOVED_BUILTIN_IDS.length; ri++) {
+  for (var ri = 0; !migrated && ri < REMOVED_BUILTIN_IDS.length; ri++) {
     fs.rmSync(path.join(root, REMOVED_BUILTIN_IDS[ri]), { recursive: true, force: 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.
+  // lib/capsules/ holds the shipped Capsules, currently the Pig validation
+  // Capsule. It may still be absent from an older checkout or tarball, and
+  // seeding also owns the removed-built-in migration above and the marker
+  // below, so a missing 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 });
@@ -185,6 +203,11 @@ function getTool(ctx, id) {
     manifest: Object.assign({}, manifest, { runtime: runtime }),
     logicSource: runtime === "worker" ? fs.readFileSync(logicPath, "utf8") : null,
     uiTree: uiTree,
+    // Rich Display is opted into by shipping a display.js next to the floor,
+    // the same way logic.js opts into the worker runtime. Only the flag
+    // travels; the source is served solely by the isolated frame origin, so
+    // it can never leak into a manifest, a prompt, or a Mate surface.
+    hasRichDisplay: fs.existsSync(path.join(directory, "display.js")),
     metadata: toolCapsuleSource.sanitizedMetadata(resolveToolsRoot(ctx), id),
   };
 }
@@ -199,8 +222,14 @@ function listTools(ctx) {
     if (entries[i].name.charAt(0) === ".") continue;
     try {
       var tool = getTool(ctx, entries[i].name);
-      if (tool) manifests.push(tool.manifest);
-      else manifests.push({ id: entries[i].name, error: "Capsule requires manifest.json and ui.json." });
+      if (tool) {
+        // The flat manifest carries its own Display alongside it, so a
+        // Mate-facing gate can validate the real tree without a second read
+        // and without trusting a claim. Non-enumerable, so the tree never
+        // leaks into a projection, a prompt, or a serialized message.
+        Object.defineProperty(tool.manifest, "uiTree", { value: tool.uiTree, enumerable: false, configurable: true });
+        manifests.push(tool.manifest);
+      } else manifests.push({ id: entries[i].name, error: "Capsule requires manifest.json and ui.json." });
     } catch (e) {
       manifests.push({ id: entries[i].name, error: e.message });
     }
@@ -216,6 +245,7 @@ function installTool(ctx, input) {
     throw new Error("Tool logic source is required.");
   }
   validateUiTreeForManifest(input.uiTree, input.manifest);
+  capsuleFloor.assertFloor(input.uiTree, input.manifest);
   var manifest = Object.assign({}, input.manifest, { name: input.manifest.name.trim(), runtime: "worker" });
   var directory = toolDirectory(ctx, manifest.id);
   if (fs.existsSync(directory)) throw new Error("A Capsule with this ID already exists. Read its source and use the update tool instead.");
@@ -253,7 +283,10 @@ function updateTool(ctx, id, input) {
   if (!tool) throw new Error("Tool not found.");
   toolCapsuleSource.updateSource(toolDirectory(ctx, id), input, {
     validateManifest: validateManifest,
-    validateUiNode: function (uiTree) { return validateUiTreeForManifest(uiTree, input.manifest); },
+    validateUiNode: function (uiTree) {
+      validateUiTreeForManifest(uiTree, input.manifest);
+      return capsuleFloor.assertFloor(uiTree, input.manifest);
+    },
   });
   return getTool(ctx, id);
 }
@@ -268,6 +301,7 @@ function removeTool(ctx, id) {
 
 module.exports = {
   CAPSULES_ROOT: CAPSULES_ROOT,
+  SEED_MARKER: SEED_MARKER,
   UI_NODE_TYPES: UI_NODE_TYPES,
   resolveToolsRoot: resolveToolsRoot,
   validateToolId: validateToolId,

package/lib/ws-schema.js

@@ -40,7 +40,7 @@ var schema = {
   "split_group_set_pair":     { direction: "c2s", handler: "lib/session-split-groups.js", description: "Assign Driver/Worker roles on a split group (driverId null clears them)" },
   "pair_session_options":     { direction: "c2s", handler: "lib/project-session-pair.js", description: "Request vendors/models for the pair-session dialog (response reuses the same type)" },
   "pair_session_create":      { direction: "c2s", handler: "lib/project-session-pair.js", description: "Create a Driver/Split Worker session pair as a split group" },
-  "worker_proposal_response": { direction: "c2s", handler: "lib/project-worker-proposal.js", description: "Accept or decline a Fable Worker suggestion with the selected runtime" },
+  "worker_proposal_response": { direction: "c2s", handler: "lib/project-worker-proposal.js", description: "Accept or decline an exact Driver Split Worker configuration with the selected runtime" },
   "project_assignment_response": { direction: "c2s", handler: "lib/workspace-assignment-service.js", description: "Approve or cancel an exact-session cross-project assignment proposal" },
   "home_clay_session_resolve": { direction: "c2s", handler: "lib/server-home-chat.js", description: "Resolve an opaque Mate session reference through the exact bound source session" },
   "home_clay_session_target": { direction: "s2c", handler: "lib/public/modules/command-palette.js", description: "Return an owner-validated navigation target for a rendered Mate session reference" },
@@ -62,8 +62,8 @@ var schema = {
   "split_groups":             { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Full persistent split-group list for the current user" },
   "split_group_result":       { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Result of a split-group mutation" },
   "pair_session_created":     { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Result of pair_session_create; carries the new group" },
-  "worker_proposal":          { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Inline Fable suggestion to delegate execution to a Worker" },
-  "worker_proposal_update":   { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Worker suggestion lifecycle update" },
+  "worker_proposal":          { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Recorded Split Worker creation/replacement runtime card with Driver rationale" },
+  "worker_proposal_update":   { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Worker card lifecycle and manual/auto decision audit update" },
   "project_assignment_proposal": { direction: "s2c", handler: "lib/public/modules/app-message-router.js", description: "Approval card for a new owner-bound project assignment" },
   "project_assignment_status": { direction: "s2c", handler: "lib/public/modules/app-message-router.js", description: "Durable project assignment lifecycle update" },
   "project_assignment_error": { direction: "s2c", handler: "lib/public/modules/app-message-router.js", description: "Rejected or stale project assignment response" },
@@ -489,6 +489,8 @@ var schema = {
   "tool_llm_op":              { direction: "c2s", handler: "lib/server-tools.js", description: "Run a permission-gated vendor-neutral capsule LLM completion" },
   "tool_llm_config_get":      { direction: "c2s", handler: "lib/server-tools.js", description: "Get the concrete configured provider and model used by Capsule LLM calls" },
   "tool_control_response":    { direction: "c2s", handler: "lib/server-tools.js", description: "Resolve a mate tool-control request with browser runtime state or an error" },
+  "tool_server_control":      { direction: "c2s", handler: "lib/server-tools.js", description: "Human snapshot or action against a server-runtime Capsule, through the same Logic a Mate calls" },
+  "tool_frame_url":           { direction: "c2s", handler: "lib/server-tools.js", description: "Mint a one-time separate-origin URL for a Capsule's sandboxed rich Display frame" },
   "tools_state":              { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Full installed tool definitions" },
   "tool_installed":           { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "An installed tool changed" },
   "tool_source_state":        { direction: "s2c", handler: "lib/public/modules/home-capsule-source.js", description: "Correlated authored Capsule source or read error" },
@@ -498,6 +500,9 @@ var schema = {
   "tool_llm_result":          { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Result of a capsule LLM completion" },
   "tool_llm_config_state":    { direction: "s2c", handler: "lib/public/modules/tool-llm-status.js", description: "Concrete provider and model state for Capsule LLM calls" },
   "tool_control_request":     { direction: "s2c", handler: "lib/public/modules/home-tools.js", description: "Ask the connected home client to snapshot or drive a sandboxed tool" },
+  "tool_server_state":        { direction: "s2c", handler: "lib/public/modules/home-tools.js", description: "Correlated server-runtime Capsule state for the human who requested it, or the refusal that blocked it" },
+  "tool_server_event":        { direction: "s2c", handler: "lib/public/modules/home-tools.js", description: "Ordered causal act event {seq, actor, action, previous, next} pushed to the user's Displays whenever server-runtime Capsule Logic changes state" },
+  "tool_frame_url_state":     { direction: "s2c", handler: "lib/public/modules/home-tool-frame.js", description: "Correlated one-time rich Display frame URL, or the refusal that blocked it" },
   "tools_error":              { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Tool registry, runtime, or storage error" },
 
   // -----------------------------------------------------------------------

package/lib/yoke/adapters/claude.js

@@ -260,6 +260,18 @@ function flattenEvent(raw) {
       base.status = raw.status;
       return base;
     }
+    // API retry notices are transient transport state, not conversation
+    // errors. Preserve the structured counters so the host can bound overload
+    // churn without recording one red error row per SDK retry.
+    if (raw.subtype === "api_retry") {
+      base.yokeType = "api_retry";
+      base.attempt = raw.attempt || 0;
+      base.maxRetries = raw.max_retries || 0;
+      base.retryDelayMs = raw.retry_delay_ms || 0;
+      base.error = raw.error || "unknown";
+      base.errorStatus = raw.error_status == null ? null : raw.error_status;
+      return base;
+    }
     if (raw.subtype === "task_started") {
       base.yokeType = "task_started";
       base.parentToolId = raw.tool_use_id;

package/package.json

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