clay-server 3.8.1 → 4.0.0-beta.2

package/lib/sdk-bridge.js

@@ -10,6 +10,7 @@ var { splitShellSegments, attachSkillDiscovery } = require("./sdk-skill-discover
 var { isSafeBashSegment } = require("./safe-bash-commands");
 var { createMessageQueue } = require("./sdk-message-queue");
 var { attachMessageProcessor } = require("./sdk-message-processor");
+var homeDebateToolPolicy = require("./home-debate-tool-policy");
 var yoke = require("./yoke");
 
 // Extract serializable tool descriptors from MCP server instances.
@@ -108,6 +109,7 @@ function createSDKBridge(opts) {
   var getNotificationsModule = opts.getNotificationsModule || function () { return null; };
   var adapter = opts.adapter;
   var adapters = opts.adapters || {};
+  var getRuntimeEnv = opts.getRuntimeEnv || function () { return process.env; };
   var mateDisplayName = opts.mateDisplayName || "";
   var isMate = opts.isMate || (slug.indexOf("mate-") === 0);
   var osUsers = !!opts.osUsers;
@@ -364,6 +366,7 @@ function createSDKBridge(opts) {
     sessionAdapter.generateTitle(userMessages, {
       cwd: cwd,
       linuxUser: getSessionLinuxUser(session) || undefined,
+      env: getRuntimeEnv(session),
     }).then(function(title) {
       if (!title || title.length < 2) return;
       title = title.substring(0, 100);
@@ -391,6 +394,7 @@ function createSDKBridge(opts) {
     mateDisplayName: mateDisplayName,
     pushModule: pushModule,
     getNotificationsModule: getNotificationsModule,
+    shouldSuppressResponseNotification: opts.shouldSuppressResponseNotification,
     adapter: adapter,
     saveImageFile: opts.saveImageFile,
     getSessionLinuxUser: getSessionLinuxUser,
@@ -573,6 +577,29 @@ function createSDKBridge(opts) {
     if (toolName.indexOf("mcp__clay-debate__") === 0) {
       return { behavior: "allow", updatedInput: input };
     }
+    if (toolName.indexOf("mcp__clay-mate-creation__") === 0) {
+      return { behavior: "allow", updatedInput: input };
+    }
+    // Structured user input only presents a question and waits for the user's
+    // answer. Yoke may expose the same query-bound capability as a native
+    // dynamic tool, its MCP fallback, or the legacy Clay MCP name.
+    if (toolName === "ask_user_questions"
+        || toolName === "mcp__yoke-user-input__ask_user_questions"
+        || toolName === "mcp__clay-ask-user__ask_user_questions") {
+      return { behavior: "allow", updatedInput: input };
+    }
+
+    var safeCapsuleTools = {
+      clay_tool_list: true,
+      clay_tool_snapshot: true,
+      clay_tool_act: true,
+      clay_tool_set: true,
+      clay_tool_source: true,
+    };
+    if (toolName.indexOf("mcp__clay-tools__") === 0
+        && safeCapsuleTools[toolName.substring(toolName.lastIndexOf("__") + 2)]) {
+      return { behavior: "allow", updatedInput: input };
+    }
 
     // Auto-approve split-pair partner tools. The pair itself is
     // user-constructed (the user created the split and its roles and
@@ -622,10 +649,20 @@ function createSDKBridge(opts) {
       }
     }
 
-    // Auto-approve clay-history tools. Mounted only on Clay (host agent)
-    // sessions and strictly read-only by design — search and read across
-    // the user's own workspace data.
-    if (toolName.indexOf("mcp__clay-history__") === 0) {
+    // Workspace inspection and proposal posting are session-bound. Keep this
+    // list exact so a future execution/mutation tool cannot inherit approval.
+    var safeWorkspaceTools = {
+      "mcp__clay-workspace__list_projects": true,
+      "mcp__clay-workspace__list_project_sessions": true,
+      "mcp__clay-workspace__search_project_history": true,
+      "mcp__clay-workspace__read_project_session": true,
+      "mcp__clay-workspace__search_workspace_history": true,
+      "mcp__clay-workspace__list_workspace_activity": true,
+      "mcp__clay-workspace__propose_project_assignment": true,
+      "mcp__clay-workspace__propose_project_follow_up": true,
+      "mcp__clay-workspace__get_assignment_status": true,
+    };
+    if (safeWorkspaceTools[toolName] || toolName.indexOf("mcp__clay-history__") === 0) {
       return { behavior: "allow", updatedInput: input };
     }
 
@@ -668,6 +705,18 @@ function createSDKBridge(opts) {
   }
 
   function handleCanUseTool(session, toolName, input, opts) {
+    var debateDecision = homeDebateToolPolicy.initialToolDecision(session, toolName, input);
+    if (debateDecision) return Promise.resolve(debateDecision);
+    // The dynamic proposal tool is bound to this exact query session. It only
+    // posts the inline proposal; starting the debate still requires the user.
+    if (session.homeDebatePlanning === true && toolName === "propose_debate") {
+      return Promise.resolve({ behavior: "allow", updatedInput: input });
+    }
+    // Mate creation proposals only present the exact-session approval card;
+    // creating the Mate still requires the user's explicit action there.
+    if (session.mateCreationMode === true && toolName === "propose_mate") {
+      return Promise.resolve({ behavior: "allow", updatedInput: input });
+    }
     // Full-auto mode: auto-approve everything except AskUserQuestion
     // (which still needs to go through the user interaction flow).
     var clayPermissionMode = session.permissionMode || sm.currentPermissionMode;
@@ -693,23 +742,6 @@ function createSDKBridge(opts) {
       return Promise.resolve(whitelisted);
     }
 
-    // AskUserQuestion: wait for user answers via WebSocket
-    if (toolName === "AskUserQuestion") {
-      return new Promise(function(resolve) {
-        session.pendingAskUser[opts.toolUseID] = {
-          resolve: resolve,
-          input: input,
-        };
-        if (opts.signal) {
-          opts.signal.addEventListener("abort", function() {
-            delete session.pendingAskUser[opts.toolUseID];
-            sendAndRecord(session, { type: "ask_user_answered", toolId: opts.toolUseID });
-            resolve({ behavior: "deny", message: "Cancelled" });
-          });
-        }
-      });
-    }
-
     // Auto-approve if tool was previously allowed for session
     if (session.allowedTools && session.allowedTools[toolName]) {
       return Promise.resolve({ behavior: "allow", updatedInput: input });
@@ -1032,19 +1064,15 @@ function createSDKBridge(opts) {
       if (ownsRuntime) {
         session.taskStopRequested = false;
         session.pendingPermissions = {};
-        // Preserve MCP-mode AskUserQuestion entries across turn boundaries.
-        // The MCP path is intentionally stateless: the tool returns immediately
-        // ("card posted, end your turn") and the user's answer is expected to
-        // arrive as a brand-new user_message on the *next* turn. That means the
-        // pending entry MUST survive this finally block. Without it, the
-        // ask_user_response handler can't find the toolId and silently drops
-        // the answer. canUseTool-mode entries (Claude's native path) still hold
-        // an open SDK permission callback that dies with the query, so those
-        // are correctly cleared here.
+        // Preserve only restored legacy MCP entries. Canonical Yoke requests
+        // hold a live provider callback and must be cancelled with their query.
         var keepAskUser = {};
         for (var _tid in session.pendingAskUser) {
           var _pending = session.pendingAskUser[_tid];
           if (_pending && _pending.mode === "mcp") keepAskUser[_tid] = _pending;
+          else if (_pending && _pending.mode === "yoke" && _pending.respond && typeof _pending.respond.cancel === "function") {
+            _pending.respond.cancel("Query closed");
+          }
         }
         session.pendingAskUser = keepAskUser;
         session.pendingElicitations = {};
@@ -1093,6 +1121,7 @@ function createSDKBridge(opts) {
       handle = await adapter.createQuery({
         cwd: cwd,
         resumeSessionId: session.cliSessionId,
+        env: getRuntimeEnv(session),
         adapterOptions: {
           CLAUDE: {
             settingSources: ["user", "project", "local"],
@@ -1209,6 +1238,7 @@ function createSDKBridge(opts) {
   }
 
   async function startQueryInner(session, text, images, linuxUser) {
+    var sessionRuntimeEnv = getRuntimeEnv(session);
     async function ensureVendorReady(vendor) {
       if (!vendor) return null;
       if (linuxUser && !supportsOsUserIsolation(vendor)) return null;
@@ -1222,6 +1252,7 @@ function createSDKBridge(opts) {
           clayTls: clayTls,
           clayAuthToken: clayAuthToken,
           slug: slug,
+          env: sessionRuntimeEnv,
         });
       }
       var needsReadyMetadata = !sm.capabilitiesByVendor || !sm.capabilitiesByVendor[vendor]
@@ -1235,6 +1266,7 @@ function createSDKBridge(opts) {
           clayTls: clayTls,
           clayAuthToken: clayAuthToken,
           slug: slug,
+          env: sessionRuntimeEnv,
         });
         rememberAdapterReady(vendor, readyResult);
       }
@@ -1477,8 +1509,37 @@ function createSDKBridge(opts) {
 
     var codexConfig = getCodexConfig(sm);
     var kiroConfig = getKiroConfig(sm);
-    var mergedMcpServers = mergeMcpServers(getMcpServers(session), getRemoteMcpServers) || undefined;
+    var requestedUserInputMode = session.debateSetupMode || session.mateCreationMode ? "fallback" : "auto";
+    var selectedUserInputMode = yoke.userInput.selectMode(sessionAdapter, requestedUserInputMode);
+    var sessionUserInputHandler = function(request, respond) {
+      if (request.presentation === "elicitation" && request.diagnostics && request.diagnostics.elicitation) {
+        var elicitationController = new AbortController();
+        if (respond && typeof respond.onSettle === "function") {
+          respond.onSettle(function (result) {
+            if (result.status !== "submitted") elicitationController.abort();
+          });
+        }
+        return handleElicitation(session, request.diagnostics.elicitation, { signal: elicitationController.signal }).then(function(result) {
+          if (result && result.action === "accept") return respond.submitContent(result.content || {});
+          return respond.cancel("Elicitation rejected");
+        });
+      }
+      if (typeof opts.onUserInputRequest !== "function") return respond.cancel("Structured user input is unavailable.");
+      return opts.onUserInputRequest(session, request, respond);
+    };
+    var localMcpServers = getMcpServers(session);
+    if (selectedUserInputMode === "fallback") {
+      var userInputServer = yoke.userInput.createFallbackServer(sessionAdapter, sessionUserInputHandler, { force: true });
+      if (userInputServer) {
+        localMcpServers = Object.assign({}, localMcpServers || {});
+        localMcpServers[userInputServer.name || "yoke-user-input"] = userInputServer;
+      }
+    }
+    var mergedMcpServers = mergeMcpServers(localMcpServers, getRemoteMcpServers) || undefined;
     var sessionToolDefs = getSessionToolDefs(session) || [];
+    if (selectedUserInputMode === "fallback") {
+      sessionToolDefs = sessionToolDefs.concat(yoke.userInput.fallbackToolDefs(sessionUserInputHandler));
+    }
 
     // Derive an explicit session title for fresh queries so the SDK records
     // it at session creation and skips its own auto-generation. This also
@@ -1503,6 +1564,7 @@ function createSDKBridge(opts) {
     var queryOpts = {
       cwd: cwd,
       linuxUser: linuxUser || undefined,
+      env: sessionRuntimeEnv,
       // appendSystemPrompt, NOT systemPrompt: a plain-string systemPrompt
       // REPLACES the entire Claude Code system prompt (sdk.d.ts:2096), which
       // would strip the driver session down to the two-sentence pair preset.
@@ -1535,8 +1597,19 @@ function createSDKBridge(opts) {
       resumeSessionId: session.cliSessionId || undefined,
       abortController: linuxUser ? undefined : session.abortController,
       canUseTool: function(toolName, input, toolOpts) {
-        return handleCanUseTool(session, toolName, input, toolOpts);
+        var permissionName = toolName;
+        for (var pti = 0; pti < sessionToolDefs.length; pti++) {
+          if (sessionToolDefs[pti].name === toolName && sessionToolDefs[pti].permissionName) {
+            permissionName = sessionToolDefs[pti].permissionName;
+            break;
+          }
+        }
+        return handleCanUseTool(session, permissionName, input, toolOpts);
       },
+      onUserInputRequest: function(request, respond) {
+        return sessionUserInputHandler(request, respond);
+      },
+      userInputMode: selectedUserInputMode,
       onElicitation: function(request, elicitOpts) {
         return handleElicitation(session, request, elicitOpts);
       },
@@ -1757,6 +1830,19 @@ function createSDKBridge(opts) {
     return true;
   }
 
+  function refreshEnvironmentRuntime() {
+    if (sm && sm.sessions) {
+      sm.sessions.forEach(function (session) { refreshSessionRuntime(session); });
+    }
+    var vendorNames = Object.keys(adapters);
+    for (var i = 0; i < vendorNames.length; i++) {
+      var runtime = adapters[vendorNames[i]];
+      if (!runtime || typeof runtime.shutdownIfIdle !== "function") continue;
+      Promise.resolve(runtime.shutdownIfIdle(0)).catch(function () {});
+    }
+    return true;
+  }
+
   function permissionPushTitle(toolName, input) {
     if (!input) return "Claude wants to use " + toolName;
     var file = input.file_path ? input.file_path.split(/[/\\]/).pop() : "";
@@ -2078,6 +2164,7 @@ function createSDKBridge(opts) {
       handle = await mentionAdapter.createQuery({
         cwd: cwd,
         linuxUser: opts.linuxUser || undefined,
+        env: getRuntimeEnv(opts.session || { linuxUser: opts.linuxUser || null }),
         systemPrompt: opts.claudeMd,
         model: opts.model || undefined,
         toolServers: opts.includeMcpServers ? (mergeMcpServers(getMcpServers(), getRemoteMcpServers) || undefined) : undefined,
@@ -2233,6 +2320,7 @@ function createSDKBridge(opts) {
     startQuery: startQuery,
     pushMessage: pushMessage,
     refreshSessionRuntime: refreshSessionRuntime,
+    refreshEnvironmentRuntime: refreshEnvironmentRuntime,
     setModel: setModel,
     setEffort: setEffort,
     setPermissionMode: setPermissionMode,

package/lib/sdk-message-processor.js

@@ -9,6 +9,7 @@ function attachMessageProcessor(ctx) {
   var mateDisplayName = ctx.mateDisplayName;
   var pushModule = ctx.pushModule;
   var getNotificationsModule = ctx.getNotificationsModule || function () { return null; };
+  var shouldSuppressResponseNotification = ctx.shouldSuppressResponseNotification || function () { return false; };
   var getSDK = ctx.getSDK;
   var adapter = ctx.adapter;
   var cwd = ctx.cwd;
@@ -484,10 +485,8 @@ function attachMessageProcessor(ctx) {
       session.pendingPermissions = {};
       session.pendingElicitations = {};
       // Record ask_user_answered for any leftover pending questions so replay pairs correctly.
-      // EXCEPTION: "mcp" mode entries are stateless — the tool returned immediately and the
-      // turn is expected to end while the card is still awaiting the user's answer. Those
-      // entries must survive across turns so the eventual ask_user_response can inject the
-      // answer as the next user message. Only blocking modes (Claude canUseTool) get closed.
+      // Restored legacy MCP entries survive across turns. Canonical Yoke
+      // requests own a live provider callback and are cancelled on turn end.
       var leftoverAskIds = Object.keys(session.pendingAskUser);
       var keptAskUser = {};
       for (var lai = 0; lai < leftoverAskIds.length; lai++) {
@@ -497,6 +496,9 @@ function attachMessageProcessor(ctx) {
           keptAskUser[lid] = lentry;
           continue;
         }
+        if (lentry && lentry.mode === "yoke" && lentry.respond && typeof lentry.respond.cancel === "function") {
+          lentry.respond.cancel("Turn ended");
+        }
         sendAndRecord(session, { type: "ask_user_answered", toolId: lid });
       }
       session.pendingAskUser = keptAskUser;
@@ -582,8 +584,10 @@ function attachMessageProcessor(ctx) {
       var _donePreviewText = (session.responsePreview || "").replace(/\s+/g, " ").trim();
       if (_donePreviewText.length > 140) _donePreviewText = _donePreviewText.substring(0, 140) + "...";
       var _doneTitle = mateDisplayName ? (mateDisplayName + " responded") : (session.title || "Claude");
+      var _suppressResponseNotification = false;
+      try { _suppressResponseNotification = shouldSuppressResponseNotification(session) === true; } catch (e) {}
 
-      if (pushModule && !session._delegatedBy) {
+      if (pushModule && !session._delegatedBy && !_suppressResponseNotification) {
         pushModule.sendPush({
           type: "done",
           slug: slug,
@@ -594,7 +598,7 @@ function attachMessageProcessor(ctx) {
       }
 
       var _nm = getNotificationsModule();
-      if (_nm && !session.loop && !session._delegatedBy) {
+      if (_nm && !session.loop && !session._delegatedBy && !_suppressResponseNotification) {
         _nm.notify("response_done", {
           title: _doneTitle,
           preview: _donePreviewText,

package/lib/server-home-capsule-creation.js

@@ -0,0 +1,36 @@
+// Validation and bounded Mate context for a Capsule creation conversation.
+
+function normalizeCapsuleDescription(value) {
+  if (typeof value !== "string") return "";
+  return value.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ").trim().slice(0, 4000);
+}
+
+function readCapsuleCreationIntent(value) {
+  if (!value || value.type !== "capsule_creation") return null;
+  var description = normalizeCapsuleDescription(value.description);
+  if (!description) {
+    var error = new Error("Describe the interface you need.");
+    error.code = "capsule_description_required";
+    throw error;
+  }
+  return { type: "capsule_creation", description: description };
+}
+
+function buildCapsuleCreationPrompt(description) {
+  return [
+    "Help the user turn the following request into a durable Capsule interface.",
+    "First inspect the need conversationally and help refine the behavior, state, and safe declarative UI.",
+    "Do not install or update a Capsule until the user has inspected the proposal and explicitly approved it through the existing permission flow.",
+    "The Capsule remains user-owned and available to all of the user's Mates.",
+    "",
+    "<capsule_request>",
+    description,
+    "</capsule_request>",
+  ].join("\n");
+}
+
+module.exports = {
+  normalizeCapsuleDescription: normalizeCapsuleDescription,
+  readCapsuleCreationIntent: readCapsuleCreationIntent,
+  buildCapsuleCreationPrompt: buildCapsuleCreationPrompt,
+};