clay-server 3.8.1 → 4.0.0-beta.10

package/lib/yoke/adapters/codex.js

@@ -10,6 +10,24 @@ var INITIALIZE_TIMEOUT_MS = require("../interface").INITIALIZE_TIMEOUT_MS;
 var skillDiscovery = require("../skill-discovery");
 var { resolveOsUserInfo } = require("../../os-users");
 var backgroundTasks = require("../codex-background-tasks");
+var codexUserInput = require("../codex-user-input");
+
+// --- Reasoning defaults ---
+// Reasoning summaries are the only readable thinking channel Codex offers:
+// raw reasoning content is encrypted for ChatGPT-authenticated models, so the
+// item/reasoning/* events this adapter already maps to thinking only carry
+// text when the app-server is asked for summaries. The CLI default
+// (`model_reasoning_summary = "auto"`) frequently produces none at all, and the
+// app-server otherwise inherits whatever is in the user's ~/.codex/config.toml,
+// so Clay asks for detailed summaries explicitly.
+//
+// `show_raw_agent_reasoning` is deliberately absent: it is encrypted on
+// ChatGPT-auth models and noisy elsewhere, so it stays a user opt-in.
+// Everything here is overridable via adapterOptions.CODEX.config.
+var CODEX_REASONING_DEFAULTS = {
+  model_reasoning_summary: "detailed",
+  model_supports_reasoning_summaries: true,
+};
 
 // --- Event flattening ---
 // Converts app-server JSON-RPC notifications into flat objects with a yokeType field.
@@ -726,6 +744,7 @@ function createCodexQueryHandle(appServer, queryOpts) {
   var canUseTool = queryOpts.canUseTool || null;
   var callDynamicTool = queryOpts.callDynamicTool || null;
   var onElicitation = queryOpts.onElicitation || null;
+  var onUserInputRequest = queryOpts.onUserInputRequest || null;
   var onFinished = queryOpts.onFinished || null;
 
   // Check if the query was cancelled (either via handle.abort() or direct signal abort)
@@ -925,12 +944,23 @@ function createCodexQueryHandle(appServer, queryOpts) {
       return;
     }
 
-    // MCP tool approval / elicitation (app-server uses mcpServer/elicitation/request)
-    if (method === "item/tool/requestUserInput" || method === "mcpServer/elicitation/request") {
+    if (method === "item/tool/requestUserInput") {
+      if (!onUserInputRequest) {
+        appServer.respondError(msg.id, -32002, "This query cannot request structured user input.");
+        return;
+      }
+      codexUserInput.handleNative(appServer, msg, onUserInputRequest, state.threadId, abortController && abortController.signal);
+      return;
+    }
+
+    // MCP elicitation shares the YOKE user-input lifecycle when available.
+    if (method === "mcpServer/elicitation/request") {
       var mcpParams = msg.params || {};
       var mcpMeta = mcpParams._meta || {};
       console.log("[yoke/codex] MCP approval request:", (mcpMeta.tool || "?"), "server=" + (mcpParams.serverName || "?"));
-      if (onElicitation) {
+      if (onUserInputRequest) {
+        codexUserInput.handleElicitation(appServer, msg, onUserInputRequest, abortController && abortController.signal);
+      } else if (onElicitation) {
         var request = {
           serverName: mcpParams.serverName || (mcpMeta.tool || "Tool"),
           message: mcpParams.message || mcpParams.prompt || "",
@@ -1049,6 +1079,7 @@ function createCodexQueryHandle(appServer, queryOpts) {
         cwd: queryOpts.cwd,
         skipGitRepoCheck: true,
       };
+      if (queryOpts.ephemeral === true) threadParams.ephemeral = true;
       if (queryOpts.modelReasoningEffort) {
         threadParams.modelReasoningEffort = queryOpts.modelReasoningEffort;
       }
@@ -1079,6 +1110,11 @@ function createCodexQueryHandle(appServer, queryOpts) {
         threadResult = await appServer.send("thread/start", threadParams, 60000);
       }
 
+      if (queryOpts.ephemeral === true
+          && (!threadResult || !threadResult.thread || threadResult.thread.ephemeral !== true)) {
+        throw new Error("Codex did not confirm an ephemeral one-shot thread.");
+      }
+
       if (threadResult && threadResult.thread) {
         state.threadId = threadResult.thread.id;
         handlerEntry.threadId = state.threadId;
@@ -1110,7 +1146,7 @@ function createCodexQueryHandle(appServer, queryOpts) {
 
         // Explicit references use Codex's native skill input item regardless of
         // which vendor owns the SKILL.md file.
-        var availableSkills = skillDiscovery.discoverSkills(queryOpts.cwd);
+        var availableSkills = queryOpts.skipSkills ? [] : skillDiscovery.discoverSkills(queryOpts.cwd);
         var skillItemsToInject = [];
         var injected = {};
         for (var ii = 0; ii < input.length; ii++) {
@@ -1293,15 +1329,14 @@ function createCodexAdapter(opts) {
   // model listing must not depend on a successful app-server init — otherwise a
   // slow/failed `initialize` leaves the picker empty and the chip shows the
   // previous vendor's model.
+  // Kept in sync with what `model/list` reports for the bundled codex build
+  // (0.152.1). Models the CLI no longer offers are rejected at turn/start, so
+  // listing them would only surface a runtime failure in the model picker.
   var CODEX_MODELS = [
     "gpt-5.6-terra",
     "gpt-5.6-sol",
     "gpt-5.6-luna",
     "gpt-5.5",
-    "gpt-5.4",
-    "gpt-5.4-mini",
-    "gpt-5.3-codex",
-    "gpt-5.3-codex-spark",
     "gpt-5.2",
   ];
   var _cachedModels = CODEX_MODELS.slice();
@@ -1516,6 +1551,7 @@ function createCodexAdapter(opts) {
 
   var adapter = {
     vendor: "codex",
+    userInputCapability: { mode: "native", native: true, transport: "item/tool/requestUserInput" },
 
     init: function(initOpts) {
       var requestedLinuxUser = initOpts && initOpts.linuxUser;
@@ -1543,17 +1579,21 @@ function createCodexAdapter(opts) {
       if (_initPromise) return _initPromise;
 
       _initPromise = (async function() {
-        var serverOpts = { cwd: _cwd };
+        var serverOpts = { cwd: _cwd, env: effectiveInitOpts.env || null };
         if (_runtimeLinuxUser) {
           serverOpts.osUserInfo = _resolveOsUserInfo(_runtimeLinuxUser);
         }
 
+        // Clay's config defaults go in first so any user-supplied
+        // adapterOptions.CODEX.config key of the same name overrides them.
+        serverOpts.config = Object.assign({}, CODEX_REASONING_DEFAULTS);
+
         // Extract adapter options
         if (effectiveInitOpts && effectiveInitOpts.adapterOptions && effectiveInitOpts.adapterOptions.CODEX) {
           var co = effectiveInitOpts.adapterOptions.CODEX;
           if (co.apiKey) serverOpts.env = Object.assign({}, serverOpts.env || {}, { OPENAI_API_KEY: co.apiKey });
           if (co.baseUrl) serverOpts.env = Object.assign({}, serverOpts.env || {}, { OPENAI_BASE_URL: co.baseUrl });
-          if (co.config) serverOpts.config = co.config;
+          if (co.config) serverOpts.config = Object.assign(serverOpts.config, co.config);
         }
 
         // Track 1: Read local MCP server definitions from ~/.clay/mcp.json
@@ -1749,9 +1789,11 @@ function createCodexAdapter(opts) {
         callDynamicTool: queryOpts.callDynamicTool || null,
         abortController: ac,
         canUseTool: queryOpts.canUseTool || null,
-        onElicitation: queryOpts.onElicitation || null,
+        onElicitation: queryOpts.userInputMode === "fallback" ? null : (queryOpts.onElicitation || null),
+        onUserInputRequest: queryOpts.userInputMode === "fallback" ? null : (queryOpts.onUserInputRequest || null),
         resumeSessionId: queryOpts.resumeSessionId || null,
         registerBackgroundTaskReset: registerBackgroundTaskReset,
+        ephemeral: queryOpts.ephemeral === true,
       };
 
       // Reasoning effort
@@ -1806,6 +1848,14 @@ function createCodexAdapter(opts) {
       return handle;
     },
 
+    createOneShotQuery: async function(queryOpts) {
+      var handle = await adapter.createQuery(Object.assign({}, queryOpts || {}, {
+        ephemeral: true,
+        resumeSessionId: null,
+      }));
+      return { handle: handle, backendPersistence: "ephemeral" };
+    },
+
     // --- Title generation ---
     generateTitle: async function(messages, opts) {
       var requestedLinuxUser = opts && opts.linuxUser;
@@ -1823,6 +1873,7 @@ function createCodexAdapter(opts) {
       var ac = new AbortController();
       var handle = await adapter.createQuery({
         cwd: (opts && opts.cwd) || _cwd,
+        env: opts && opts.env,
         systemPrompt: systemPrompt,
         model: "gpt-5.4-mini",
         abortController: ac,
@@ -1892,6 +1943,23 @@ function createCodexAdapter(opts) {
       ]).then(function() { return true; });
     },
 
+    // A device login writes credentials for one OS identity. Refresh only
+    // that identity in OS-isolated deployments; single-user projects restart
+    // their sole app-server.
+    refreshAuthIdentity: function(linuxUser) {
+      if (!_runtimeLinuxUser && linuxUser) {
+        var userRuntime = _userRuntimes[linuxUser];
+        if (!userRuntime) return Promise.resolve(false);
+        return userRuntime.shutdown().then(function() {
+          delete _userRuntimes[linuxUser];
+          return true;
+        });
+      }
+      if (_runtimeLinuxUser && linuxUser !== _runtimeLinuxUser) return Promise.resolve(false);
+      if (_requiresLinuxUser) return Promise.resolve(false);
+      return adapter.shutdown();
+    },
+
     shutdownIfIdle: function(idleMs) {
       if (!_runtimeLinuxUser && Object.keys(_userRuntimes).length > 0) {
         return shutdownUserRuntimes("shutdownIfIdle", idleMs).then(function(results) {

package/lib/yoke/adapters/kiro.js

@@ -1065,7 +1065,7 @@ function createKiroAdapter(opts) {
       var model = queryOpts.model || _defaultModel || "auto";
       var ac = queryOpts.abortController || new AbortController();
       var kiroOpts = (queryOpts.adapterOptions && queryOpts.adapterOptions.KIRO) || {};
-      var sharedSkills = skillDiscovery.discoverSkills(queryOpts.cwd || _cwd);
+      var sharedSkills = queryOpts.skipSkills ? [] : skillDiscovery.discoverSkills(queryOpts.cwd || _cwd);
       var skillIndex = skillDiscovery.buildSkillIndex(sharedSkills);
 
       var activeEntry = { abort: function() { try { ac.abort(); } catch (e) {} } };
@@ -1123,6 +1123,7 @@ function createKiroAdapter(opts) {
       var ac = new AbortController();
       var handle = await adapter.createQuery({
         cwd: (opts && opts.cwd) || _cwd,
+        env: opts && opts.env,
         systemPrompt: systemPrompt,
         model: "auto",
         abortController: ac,

package/lib/yoke/claude-user-input.js

@@ -0,0 +1,38 @@
+// Claude SDK mappings for YOKE structured user input.
+var userInput = require("./user-input");
+
+function ask(handler, input, opts) {
+  opts = opts || {};
+  return userInput.dispatchUserInput(handler, input, {
+    requestId: opts.toolUseID || opts.requestId,
+    signal: opts.signal,
+    source: "claude_ask_user_question",
+    native: true,
+    provider: "claude",
+  }).then(function (result) { return userInput.claudePermissionResult(input, result); });
+}
+
+function elicitation(handler, request, opts) {
+  opts = opts || {};
+  return userInput.dispatchUserInput(handler, userInput.questionsFromElicitation(request), {
+    requestId: opts.requestId || request.elicitationId,
+    signal: opts.signal,
+    source: "claude_elicitation",
+    native: true,
+    provider: "claude",
+    presentation: "elicitation",
+    diagnostics: { elicitation: request },
+  }).then(userInput.elicitationResponse);
+}
+
+function canUseTool(queryOpts) {
+  var original = queryOpts.canUseTool;
+  return function (toolName, input, opts) {
+    if (toolName === "AskUserQuestion" && typeof queryOpts.onUserInputRequest === "function") return ask(queryOpts.onUserInputRequest, input, opts);
+    if (toolName === "AskUserQuestion") return Promise.resolve({ behavior: "deny", message: "Use the query's structured input fallback tool." });
+    if (original) return original(toolName, input, opts);
+    return Promise.resolve({ behavior: "deny", message: "No tool permission handler is available." });
+  };
+}
+
+module.exports = { ask: ask, elicitation: elicitation, canUseTool: canUseTool };

package/lib/yoke/codex-app-server.js

@@ -13,7 +13,13 @@ var { buildUserEnv } = require("../build-user-env");
 var { wrapSpawnAsUser } = require("../os-users");
 
 // --- Find the codex binary path ---
-// Mirrors the logic from @openai/codex-sdk findCodexPath()
+// Mirrors the logic from @openai/codex-sdk findCodexPath().
+//
+// The bundled @openai/codex platform package is the default. Set the
+// CLAY_CODEX_PATH env var to an existing executable to run a different codex
+// build (local dev build, system install, pinned older release); the chosen
+// binary is logged on every resolution. An unset or non-existent
+// CLAY_CODEX_PATH silently falls back to the bundled resolution.
 
 var PLATFORM_PACKAGE_BY_TARGET = {
   "aarch64-apple-darwin": "@openai/codex-darwin-arm64",
@@ -39,6 +45,15 @@ function getTargetTriple() {
 }
 
 function findCodexPath() {
+  var override = process.env.CLAY_CODEX_PATH;
+  if (override) {
+    if (fs.existsSync(override)) {
+      console.log("[codex-app-server] Using CLAY_CODEX_PATH binary:", override);
+      return override;
+    }
+    console.warn("[codex-app-server] CLAY_CODEX_PATH does not exist, falling back to bundled codex:", override);
+  }
+
   var triple = getTargetTriple();
   if (!triple) throw new Error("Unsupported platform: " + process.platform + "/" + process.arch);
 
@@ -59,7 +74,10 @@ function findCodexPath() {
       path.join(vendorRoot, triple, "codex", binaryName),
     ];
     for (var i = 0; i < candidates.length; i++) {
-      if (fs.existsSync(candidates[i])) return candidates[i];
+      if (fs.existsSync(candidates[i])) {
+        console.log("[codex-app-server] Using bundled codex binary:", candidates[i]);
+        return candidates[i];
+      }
     }
     throw new Error("codex binary not found in any known layout under " + path.join(vendorRoot, triple));
   } catch (e) {

package/lib/yoke/codex-background-tasks.js

@@ -19,11 +19,17 @@ function mapTerminals(result) {
     var terminal = terminals[i] || {};
     var taskId = terminal.id || terminal.terminalId || terminal.taskId || "";
     if (!taskId || !isLiveTerminal(terminal)) continue;
-    tasks.push({
+    var task = {
       task_id: String(taskId),
       task_type: "shell",
       description: terminal.commandLine || terminal.command || terminal.name || "",
-    });
+    };
+    // Forward the terminal's own start time when the app-server reports one,
+    // so elapsed time survives a Clay restart. Falls back to first-seen
+    // stamping in background-task-timing.js when absent.
+    var startedAt = terminal.startedAt || terminal.started_at || terminal.createdAt || terminal.created_at;
+    if (startedAt) task.started_at = startedAt;
+    tasks.push(task);
   }
   return tasks;
 }

package/lib/yoke/codex-user-input.js

@@ -0,0 +1,64 @@
+// Codex app-server 0.147 structured user-input protocol mapping.
+var userInput = require("./user-input");
+
+function nativeInput(params) {
+  return {
+    questions: (params.questions || []).map(function (question) {
+      return {
+        id: question.id,
+        header: question.header || "",
+        question: question.question,
+        allowOther: question.isOther !== false,
+        secret: question.isSecret === true,
+        options: Array.isArray(question.options) ? question.options : [],
+      };
+    }),
+  };
+}
+
+function handleNative(appServer, msg, handler, expectedThreadId, signal) {
+  var params = msg.params || {};
+  if (!params.threadId || (expectedThreadId && params.threadId !== expectedThreadId)) {
+    appServer.respondError(msg.id, -32001, "Structured input request does not belong to this query thread.");
+    return;
+  }
+  userInput.dispatchUserInput(handler, nativeInput(params), {
+    requestId: params.itemId || String(msg.id),
+    signal: signal,
+    source: "codex_request_user_input",
+    native: true,
+    provider: "codex",
+    diagnostics: { threadId: params.threadId, turnId: params.turnId || null, itemId: params.itemId || null },
+  }).then(function (result) {
+    appServer.respond(msg.id, userInput.codexResponse(result));
+  }).catch(function (error) {
+    appServer.respondError(msg.id, -32602, error.message);
+  });
+}
+
+function handleElicitation(appServer, msg, handler, signal) {
+  var params = msg.params || {};
+  var request = {
+    serverName: params.serverName || (params._meta && params._meta.tool) || "Tool",
+    message: params.message || params.prompt || "",
+    url: params.url || null,
+    elicitationId: params.elicitationId || null,
+    requestedSchema: params.requestedSchema || null,
+  };
+  var input = Array.isArray(params.questions) ? nativeInput(params) : userInput.questionsFromElicitation(request);
+  userInput.dispatchUserInput(handler, input, {
+    requestId: request.elicitationId || String(msg.id),
+    signal: signal,
+    source: "codex_mcp_elicitation",
+    native: true,
+    provider: "codex",
+    presentation: "elicitation",
+    diagnostics: { threadId: params.threadId || null, elicitation: request },
+  }).then(function (result) {
+    appServer.respond(msg.id, userInput.elicitationResponse(result));
+  }).catch(function (error) {
+    appServer.respondError(msg.id, -32602, error.message);
+  });
+}
+
+module.exports = { nativeInput: nativeInput, handleNative: handleNative, handleElicitation: handleElicitation };

package/lib/yoke/complete-once.js

@@ -0,0 +1,164 @@
+// Canonical single-turn completion lifecycle for YOKE adapters.
+
+function assistantMessageText(event) {
+  if (!event || event.yokeType !== "message" || event.messageRole !== "assistant") return "";
+  if (!Array.isArray(event.content)) return "";
+  var text = "";
+  for (var i = 0; i < event.content.length; i++) {
+    if (event.content[i] && event.content[i].type === "text" && event.content[i].text) {
+      text += event.content[i].text;
+    }
+  }
+  return text;
+}
+
+function normalizedText(streamedText, finalText) {
+  if (!streamedText) return finalText;
+  if (!finalText) return streamedText;
+  if (finalText.indexOf(streamedText) === 0) return finalText;
+  if (streamedText.indexOf(finalText) === 0) return streamedText;
+  return streamedText;
+}
+
+function oneShotError(event) {
+  if (!event) return null;
+  if (event.yokeType === "error") return new Error(event.text || "One-shot completion failed.");
+  if (event.yokeType === "auth_required") {
+    return new Error("The " + (event.vendor || "selected") + " provider requires sign-in.");
+  }
+  return null;
+}
+
+async function createOneShot(adapter, queryOpts, allowUnknownPersistence) {
+  if (typeof adapter.createOneShotQuery === "function") {
+    var created = await adapter.createOneShotQuery(queryOpts);
+    if (!created || !created.handle) throw new Error("YOKE adapter returned an invalid one-shot query.");
+    if (created.backendPersistence !== "ephemeral") {
+      if (!allowUnknownPersistence) {
+        if (typeof created.handle.abort === "function") created.handle.abort();
+        if (typeof created.handle.close === "function") created.handle.close();
+        throw new Error("The " + adapter.vendor + " adapter did not confirm ephemeral one-shot execution.");
+      }
+      created.backendPersistence = "unknown";
+    }
+    return created;
+  }
+  if (!allowUnknownPersistence) {
+    throw new Error("The " + adapter.vendor + " adapter does not guarantee ephemeral one-shot execution.");
+  }
+  return {
+    handle: await adapter.createQuery(Object.assign({}, queryOpts, { persistSession: false })),
+    backendPersistence: "unknown",
+  };
+}
+
+async function completeOnce(adapter, opts) {
+  opts = opts || {};
+  if (!adapter || typeof adapter.createQuery !== "function") throw new Error("A YOKE adapter is required.");
+  if (typeof opts.prompt !== "string" || !opts.prompt.trim()) throw new Error("A one-shot prompt is required.");
+
+  var timeoutMs = opts.timeoutMs || 60000;
+  var controller = new AbortController();
+  var handle = null;
+  var timedOut = false;
+  var externallyAborted = false;
+  var timer = null;
+  var externalSignal = opts.signal || null;
+  var abortHandle = function() {
+    controller.abort();
+    if (handle && typeof handle.abort === "function") handle.abort();
+  };
+  var onExternalAbort = function() {
+    externallyAborted = true;
+    abortHandle();
+  };
+
+  if (externalSignal) {
+    if (externalSignal.aborted) onExternalAbort();
+    else externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+  }
+  timer = setTimeout(function() {
+    timedOut = true;
+    abortHandle();
+  }, timeoutMs);
+
+  var streamedText = "";
+  var finalText = "";
+  var resultEvent = null;
+  var interactiveRequested = false;
+  var created;
+  try {
+    var queryOpts = Object.assign({}, opts.query || {}, {
+      cwd: opts.cwd,
+      model: opts.model,
+      systemPrompt: opts.systemPrompt,
+      abortController: controller,
+      onUserInputRequest: function (request, respond) {
+        interactiveRequested = true;
+        respond.cancel("One-shot completions cannot request interactive user input.");
+      },
+    });
+    var creationFinished = false;
+    var rejectCreation;
+    var creationAbort = new Promise(function(resolve, reject) { rejectCreation = reject; });
+    var onCreationAbort = function() { rejectCreation(new Error("One-shot completion aborted.")); };
+    controller.signal.addEventListener("abort", onCreationAbort, { once: true });
+    var creation = createOneShot(adapter, queryOpts, !!opts.allowUnknownBackendPersistence);
+    creation.then(function(lateCreated) {
+      if (!creationFinished && controller.signal.aborted && lateCreated && lateCreated.handle) {
+        if (typeof lateCreated.handle.abort === "function") lateCreated.handle.abort();
+        if (typeof lateCreated.handle.close === "function") lateCreated.handle.close();
+      }
+    }).catch(function() {});
+    try {
+      created = await Promise.race([creation, creationAbort]);
+      creationFinished = true;
+    } finally {
+      controller.signal.removeEventListener("abort", onCreationAbort);
+    }
+    handle = created.handle;
+    if (controller.signal.aborted) {
+      if (typeof handle.abort === "function") handle.abort();
+      throw new Error("One-shot completion aborted.");
+    }
+    if (handle.pushMessage(opts.prompt) !== true) {
+      throw new Error("YOKE one-shot query rejected its prompt.");
+    }
+    handle.endInput();
+
+    for await (var event of handle) {
+      var eventError = oneShotError(event);
+      if (eventError) throw eventError;
+      if (event.yokeType === "text_delta" && event.text) streamedText += event.text;
+      var messageText = assistantMessageText(event);
+      if (messageText) finalText = messageText;
+      if (event.yokeType === "result") {
+        resultEvent = event;
+        break;
+      }
+    }
+    if (timedOut) throw new Error("YOKE one-shot timed out after " + timeoutMs + " ms.");
+    if (externallyAborted) throw new Error("YOKE one-shot was aborted.");
+    if (interactiveRequested) throw new Error("YOKE one-shot completion requested interactive user input.");
+    return {
+      text: normalizedText(streamedText, finalText).trim(),
+      backendPersistence: created.backendPersistence || "unknown",
+      vendor: adapter.vendor,
+      model: opts.model || null,
+      result: resultEvent,
+    };
+  } catch (error) {
+    if (timedOut) throw new Error("YOKE one-shot timed out after " + timeoutMs + " ms.");
+    if (externallyAborted) throw new Error("YOKE one-shot was aborted.");
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    if (externalSignal) externalSignal.removeEventListener("abort", onExternalAbort);
+    if (handle && typeof handle.close === "function") handle.close();
+  }
+}
+
+module.exports = {
+  completeOnce: completeOnce,
+  normalizedText: normalizedText,
+};

package/lib/yoke/index.js

@@ -4,6 +4,8 @@
 var iface = require("./interface");
 var instructions = require("./instructions");
 var vendorRegistry = require("./vendor-registry");
+var completeOnce = require("./complete-once").completeOnce;
+var userInput = require("./user-input");
 var createClaudeAdapter = require("./adapters/claude").createClaudeAdapter;
 var createCodexAdapter = require("./adapters/codex").createCodexAdapter;
 var createAntigravityAdapter = require("./adapters/antigravity").createAntigravityAdapter;
@@ -47,7 +49,7 @@ function wrapCreateQuery(adapter, defaultCwd) {
   adapter.createQuery = function(queryOpts) {
     queryOpts = queryOpts || {};
     var projectDir = (queryOpts && queryOpts.cwd) || defaultCwd;
-    var merged = instructions.scanAndMerge(projectDir, adapter.vendor);
+    var merged = queryOpts.skipProjectInstructions ? "" : instructions.scanAndMerge(projectDir, adapter.vendor);
 
     if (merged) {
       var parts = [];
@@ -473,4 +475,6 @@ module.exports = {
   TOOL_POLICIES: iface.TOOL_POLICIES,
   validateAdapter: iface.validateAdapter,
   validateQueryHandle: iface.validateQueryHandle,
+  completeOnce: completeOnce,
+  userInput: userInput,
 };

package/lib/yoke/interface.js

@@ -40,6 +40,25 @@ var INITIALIZE_TIMEOUT_MS = 90000;
  *   .createToolServer(def): ToolServer (opaque)
  *   .createQuery(opts): QueryHandle
  *
+ * Optional one-shot capability:
+ *   .createOneShotQuery(opts): Promise<{ handle, backendPersistence }>
+ *     backendPersistence is "ephemeral" only when the adapter can verify the
+ *     provider does not materialize the backend conversation. Adapters without
+ *     this method may only use completeOnce's explicit unknown-persistence path.
+ *
+ * Optional structured user-input capability:
+ *   .userInputCapability: { mode: "native"|"fallback", native: boolean, transport: string }
+ *   createQuery({ userInputMode: "auto"|"native"|"fallback",
+ *                 onUserInputRequest(request, respond) })
+ *     request.presentation is "questions" or "elicitation";
+ *     request.questions contain 1-3 { id, header, question, multiSelect,
+ *     allowOther, secret, options }; options contain zero or 2-6 safe
+ *     { label, description } entries. respond(answerMap),
+ *     respond.submitContent(typedMap), and respond.cancel(reason) settle
+ *     exactly once. submitContent preserves typed MCP elicitation forms.
+ *     Adapters with mode "native" translate their provider protocol directly.
+ *     Other adapters use createFallbackServer() from yoke/user-input.
+ *
  * Lightweight utilities:
  *   .generateTitle(messages, opts) : Promise<string> - generate a short session title
  *     messages: string[] - user messages to derive the title from

package/lib/yoke/mcp-bridge-server.js

@@ -102,12 +102,8 @@ function postJson(urlPath, body) {
       reject(err);
     });
 
-    // 10 min safety ceiling. ask_user_questions is stateless (returns
-    // immediately; the user's answer arrives on the next turn as a new
-    // user message), so no tool call should legitimately block long.
-    // The generous ceiling is just a belt-and-suspenders against slow
-    // browser automation or external MCP servers, not the primary
-    // mechanism for human-in-the-loop tools.
+    // 10 min safety ceiling. Structured user input may legitimately wait
+    // for a person, while other tools normally return much sooner.
     req.setTimeout(600000, function () {
       req.destroy(new Error("Request timed out"));
     });