clay-server 5.2.0-beta.5 → 5.2.0-beta.7

package/lib/yoke/interface.js

@@ -21,6 +21,25 @@ var INITIALIZE_TIMEOUT_MS = 90000;
 
 /*
  * Optional adapter event contract:
+ *   { yokeType: "turn_activity", phase: "waiting" | "running" | "background", turnId?, disposition? }
+ * Waiting reports a pending submission/acknowledged queue, never model
+ * reasoning. Running requires an observed native start. Background means the
+ * foreground yielded while real terminals remain pending. These presentation
+ * facts never settle a turn or authorize tools; human decision surfaces take
+ * precedence. Common processing records them for live/replayed progress UI.
+ *
+ *   { yokeType: "foreground_available" }
+ * Observed next-message admission while background work retains its real
+ * terminal. Offers one queue admission bound to this exact live query. Does
+ * not emit result/done, clear processing, settle reviews or complete tasks.
+ * Common processing persists an assistant_boundary presentation event before
+ * offering admission. Live/replayed clients flush the current assistant bubble
+ * at this boundary without treating it as a terminal or completing tools.
+ * Stop, paused delivery and query replacement invalidate the admission.
+ * A later successful result may carry backgroundOnly: true when its earlier
+ * foreground yielded to a newer accepted message. It accounts for that send
+ * without settling the newer turn's reviews or user-work completion callbacks.
+ *
  *   { yokeType: "background_tasks_changed", tasks: [{ task_id, task_type, description }] }
  *
  * Each event replaces the complete live set. An adapter that emits this event
@@ -29,6 +48,25 @@ var INITIALIZE_TIMEOUT_MS = 90000;
  * and adapters that emit nothing simply have no background-task indicator.
  */
 
+/*
+ * Optional image output event (independent of image input or invocation APIs):
+ *   { yokeType: "generated_image", toolId, blockId, data, mediaType,
+ *     prompt, savedPath, transparentBackground, isError, status }
+ * data is base64 image bytes (the common processor also accepts data URLs).
+ * toolId identifies this output; blockId associates any existing tool display.
+ * prompt is optional observed prompt text; savedPath is optional provenance,
+ * never authority to open a provider path. transparentBackground is true/false
+ * only when observed, otherwise null. Failed output sets isError and carries
+ * no successful image bytes. Common processing saves bytes, persists imageRefs
+ * and sends authenticated project URLs; failed saves become tool errors.
+ * The historical name covers provider-produced image artifacts, not proof of
+ * model generation. Emit only observed bytes, never an input echo, guessed
+ * filename or opaque artifact reference. Codex normalizes imageGeneration;
+ * Muse can read an explicitly typed raster outputRef through item/readOutput.
+ * This optional event does not imply pushMessage image-input support, an
+ * always-available model tool, or a dedicated adapter.generateImage() method.
+ */
+
 /**
  * Validate that an adapter object implements all required methods.
  * Throws if any are missing. Development-time safety net only.
@@ -40,6 +78,84 @@ var INITIALIZE_TIMEOUT_MS = 90000;
  *   .createToolServer(def): ToolServer (opaque)
  *   .createQuery(opts): QueryHandle
  *
+ * Optional query orchestration contract (.queryContract):
+ *   toolTransport: "sdk-mcp" | "dynamic" | "stdio-mcp" (absent: unsupported)
+ *   catalogLifetime: "query" | "conversation"
+ *   externalToolTransport?: "dynamic" for remotely discovered definitions
+ *   defaultUserInputMode?: "fallback" | "native" (auto otherwise)
+ *   questionGuidance?(): string; provider-specific protocol guidance
+ *   permissionModes?: string[]; implemented native modes, e.g. "auto"
+ *   mcpPermissionOverrides?: true only for a working handle override setter
+ *   interruptionMessage?: string; truthful feedback after Stop
+ *   catalogVersion?(session, family): number
+ *   recordCatalog?(session, versions): void
+ *   staleCatalogReason?: string
+ *
+ * Conversation catalogs are immutable on resume. The host uses semantic tool
+ * families (schedules, questions, browser, issues, knowledge, linear) and their
+ * required revisions to request an exact-query recovery bridge. Adapter-owned
+ * mapping reads/writes persisted provider fields, including legacy names. A
+ * missing reader means unknown catalog; a missing writer never records success.
+ * Writers run only after a matching session_started event on the same live
+ * session/query generation. Creating a handle alone is not catalog confirmation.
+ * SDK transports must actually mount createToolServer output; dynamic transports
+ * must dispatch dynamicTools/callDynamicTool and deliver sessionMcpServer on
+ * resume or reject startup truthfully. These declarations never authorize tools:
+ * owner/foreign checks, target/review authority and live generation checks remain
+ * in common services. Stop cancels pending input/effects immediately; uncertain
+ * effects must not replay automatically. Provider protocols stay adapter-side.
+ * Init-free contracts live beside adapters and are also exposed by the registry
+ * for product controls before adapter initialization. Other providers retain
+ * their existing declared stdio transport or default to unsupported.
+ *
+ * Init-free provider services (adapter.providerContract or registry entry):
+ *   mapQueryOptions(intent): object. Translates validated common intent to SDK
+ *     namespaces; host never builds CLAUDE/CODEX/ACP/KIRO envelopes. Intent
+ *     includes settings, thinking, nativePermissionMode/nativeBypass, readOnly,
+ *     isolation, resumeAt, instructionSources, betas and start time. readOnly
+ *     must dominate bypass, sandbox and search options. Unknown providers have
+ *     no extra options; declared invalid/missing implementations must not imply
+ *     success. Legacy persisted names remain accepted through provider codecs.
+ *   configuration: serializable permission/thinking/approval/sandbox/search
+ *     descriptions. These describe supported controls, never authorization.
+ *   settings: defaults(), messages(settings), change(message, settings) returns
+ *     a validated patch and response; host owns persistence and socket access.
+ *   normalizeContext(value): { usedTokens, windowTokens, measurement, source }.
+ *     measurement is observed, estimated or unavailable. Zero is a measurement;
+ *     unknown is null. Billing totals are not context occupancy. YOKE usage
+ *     projects result/account-quota history to the same client contract.
+ *   authenticationReply(text), classifyError(text): protocol interpretation.
+ *     Host handles authenticationRequired and classified errors, preserving
+ *     identity, user-visible failure and explicit resumption requirements.
+ *   resolveExecutable(options): path|null; discovery never runs the provider.
+ *     Explicit supported overrides win; mapped users cannot inherit daemon
+ *     credentials/installations. Errors or missing resolvers mean unavailable.
+ *   login command/host metadata: only known validated token-only operations;
+ *     OAuth URLs require exact hosts, PKCE, state and a loopback callback.
+ *     Host still authorizes the exact owner/terminal and async flow revision.
+ *   prepareIsolation, processControl: provider filesystem/PID protocol. Host
+ *     authorizes identity and the exact process target before effects; absent
+ *     verification refuses termination. No arbitrary shell/API dispatch.
+ *   recoveryFactory(ctx): actual begin/enqueue/event/progress/cancel/current/
+ *     valid/stopping/dispose implementation. Only the implemented confirmed
+ *     termination protocol may retry; never replay uncertain delivery. Bindings
+ *     retain the original service for immediate Stop and reject replacement
+ *     providers. Unsupported providers receive no synthesized watchdog/retry.
+ *   readSessionHistory(home, cwd, sessionId): actual provider fork-history
+ *     reader. Local-history forks bypass file reading. Missing/nonfunction
+ *     readers refuse; the host must not assume another provider's format.
+ *   supportsLegacyGuiResume(session): implements the actual terminal format;
+ *     the host retains idle/Stop/identity admission and persistence authority.
+ *   notificationHooks, maintenance, provisionUser, credentialDirectories:
+ *     bounded provider services; host owns provisioning and cleanup policy.
+ *
+ * publicInfo() sends only an explicit serializable field allowlist. Executable
+ * callbacks/services, OAuth internals and factories are never client metadata.
+ * Unknown/unsupported transports normalize to none. Declared SDK MCP transport
+ * with requested definitions must have a callable factory and non-null result;
+ * errors fail startup before admission. Capability data never grants canonical
+ * registry/query-generation authority, owner permissions or human review.
+ *
  * Optional one-shot capability:
  *   .createOneShotQuery(opts): Promise<{ handle, backendPersistence }>
  *     backendPersistence is "ephemeral" only when the adapter can verify the

package/lib/yoke/kiro-acp-server.js

@@ -8,9 +8,9 @@ var fs = require("fs");
 var { AcpProcessManager } = require("./acp-process-manager");
 
 function findKiroPath() {
-  if (process.env.KIRO_CLI_PATH && fs.existsSync(process.env.KIRO_CLI_PATH)) {
-    return process.env.KIRO_CLI_PATH;
-  }
+  var discovery = require("./discovery");
+  var explicit = discovery.explicitEntry(process.env, "KIRO_CLI_PATH", false);
+  if (explicit !== undefined) return explicit;
 
   var binName = process.platform === "win32" ? "kiro-cli.exe" : "kiro-cli";
   var realHome;
@@ -23,7 +23,7 @@ function findKiroPath() {
     "/opt/homebrew/bin/" + binName,
   ];
   for (var i = 0; i < candidates.length; i++) {
-    if (candidates[i] && fs.existsSync(candidates[i])) return candidates[i];
+    if (discovery.validEntry(candidates[i], false)) return candidates[i];
   }
 
   try {
@@ -32,7 +32,7 @@ function findKiroPath() {
       ? execFileSync("where", [binName], { timeout: 3000, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] })
       : execFileSync("which", ["kiro-cli"], { timeout: 3000, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
     var resolved = out.trim().split(/\r?\n/)[0];
-    if (resolved) return resolved;
+    if (discovery.validEntry(resolved, false)) return resolved;
   } catch (e) {}
 
   throw new Error("Could not find kiro-cli binary (looked in ~/.local/bin, PATH, KIRO_CLI_PATH)");

package/lib/yoke/legacy-sessions.js

@@ -0,0 +1,89 @@
+// The existing imported terminal format. Product session creation/deletion
+// remains in the host; these are provider file/grammar projections only.
+var fs = require("fs"), path = require("path");
+var hygiene = require("./claude-transcript-hygiene");
+function directory(home, cwd) { return path.join(home, ".claude", "projects", require("../utils").encodeCwd(cwd)); }
+  function readHead(filePath) {
+    var MAX_READ = 64 * 1024;
+    try {
+      var stat = fs.statSync(filePath);
+      var fd = fs.openSync(filePath, "r");
+      var bytesToRead = Math.min(stat.size, MAX_READ);
+      var buf = Buffer.alloc(bytesToRead);
+      fs.readSync(fd, buf, 0, bytesToRead, 0);
+      fs.closeSync(fd);
+      var lines = buf.toString("utf8").split("\n");
+      var events = [];
+      for (var i = 0; i < lines.length; i++) {
+        if (!lines[i]) continue;
+        try {
+          var event = JSON.parse(lines[i]);
+          if (event && typeof event === "object") events.push(event);
+        } catch (e) {}
+      }
+      return events;
+    } catch (e) {
+      return null;
+    }
+  }
+
+function metadata(events, fp) {
+      var userCount = 0;
+      var firstUserText = null;
+      var createdAtIso = null;
+      for (var li = 0; li < events.length; li++) {
+        var ev = events[li];
+        if (ev.type === "user" && ev.message && ev.message.role === "user") {
+          userCount++;
+          if (firstUserText == null) {
+            var c = ev.message.content;
+            if (typeof c === "string") {
+              firstUserText = c;
+            } else if (Array.isArray(c)) {
+              var parts = [];
+              for (var ci = 0; ci < c.length; ci++) {
+                if (c[ci] && c[ci].type === "text" && typeof c[ci].text === "string") parts.push(c[ci].text);
+              }
+              firstUserText = parts.join("");
+            }
+            if (ev.timestamp && !createdAtIso) createdAtIso = ev.timestamp;
+          }
+        }
+      }
+
+      if (userCount === 0) return null;
+      // Defensive warmup skip (daemon also cleans these)
+      if (hygiene.isClaudeWarmupTranscript(events)) return null;
+
+      // Title: first user message trimmed/truncated. Fall back to a
+      // neutral label so the sidebar entry is identifiable.
+      var title = (firstUserText || "").trim().replace(/\s+/g, " ");
+      if (title.length > 60) title = title.slice(0, 57) + "...";
+      if (!title) title = "Imported CLI session";
+
+      var createdAt = Date.now();
+      if (createdAtIso) {
+        var t = Date.parse(createdAtIso);
+        if (!isNaN(t)) createdAt = t;
+      }
+      var lastActivity = createdAt;
+      try { lastActivity = fs.statSync(fp).mtimeMs; } catch (e) {}
+
+return { title: title, createdAt: createdAt, lastActivity: lastActivity };
+}
+function candidates(dir, known, deleted) {
+  var files;
+  try { files = fs.readdirSync(dir); } catch (error) { return []; }
+  return files.filter(function(file) { return file.endsWith(".jsonl"); }).flatMap(function(file) {
+    var id = file.slice(0, -6);
+    if (known.has(id) || deleted.has(id)) return [];
+    var filename = path.join(dir, file), events = readHead(filename);
+    var value = events && metadata(events, filename);
+    return value ? [Object.assign({ id: id, vendor: "claude" }, value)] : [];
+  });
+}
+function obsolete(dir, session) {
+  var filename = path.join(dir, session.cliSessionId + ".jsonl"), events = readHead(filename);
+  return !fs.existsSync(filename) && (!session.history || session.history.length === 0) || events && hygiene.isClaudeWarmupTranscript(events);
+}
+module.exports = { candidates: candidates, obsolete: obsolete, directory: directory, readHead: readHead, metadata: metadata, isWarmup: hygiene.isClaudeWarmupTranscript };

package/lib/yoke/login-protocol.js

@@ -0,0 +1,25 @@
+// Known provider login operations and output grammar; never accepts a command
+// from model/client input. Identity and terminal permission stay in the host.
+var PATTERNS = [/successfully logged in(?![ \t]+to[ \t]+mcp)/i, /logged in successfully/i, /login successful/i,
+  /successfully authenticated/i, /authentication successful/i, /signed in successfully/i,
+  /signed in with your [a-z ]+ account/i, /you(?:'re| are) (?:now )?(?:logged|signed) in/i];
+function stripAnsi(text) { return String(text).replace(/\x1b\[[0-9;?]*[ -\/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\r/g, ''); }
+function successful(text) { return PATTERNS.some(function(pattern) { return pattern.test(text); }); }
+function command(vendor, browser) {
+  var info = require('./provider-contract').resolve(vendor);
+  var operation = browser ? info.browserLoginCommand : info.terminalLoginCommand || info.loginCommand;
+  if (typeof operation !== 'string' || !/^[a-zA-Z0-9_.-]+(?: [a-zA-Z0-9_.-]+)*$/.test(operation)) throw new Error('Provider sign-in is unavailable.');
+  return operation;
+}
+function loginUrl(value, provider) {
+  try {
+    var hosts = require('./provider-contract').resolve(provider).oauthHosts || [];
+    var url = new URL(value);
+    if (url.protocol !== 'https:' || url.username || url.password || hosts.indexOf(url.hostname) < 0) return null;
+    if (!url.searchParams.get('state') || !url.searchParams.get('code_challenge')) return null;
+    var callback = new URL(url.searchParams.get('redirect_uri'));
+    if (callback.protocol !== 'http:' || ['localhost', '127.0.0.1', '[::1]'].indexOf(callback.hostname) < 0) return null;
+    return url.href;
+  } catch (error) { return null; }
+}
+module.exports = { stripAnsi: stripAnsi, successful: successful, command: command, loginUrl: loginUrl };

package/lib/yoke/maintenance.js

@@ -0,0 +1,12 @@
+function cleanup(home) {
+  var registry = require("./vendor-registry").VENDOR_REGISTRY;
+  Object.keys(registry).forEach(function(vendor) {
+    var service = registry[vendor].maintenance;
+    if (service && typeof service.cleanup === "function") service.cleanup(home);
+  });
+}
+function credentialPaths(home) {
+  var registry = require("./vendor-registry").VENDOR_REGISTRY, path = require("path");
+  return Object.keys(registry).flatMap(function(vendor) { return (registry[vendor].credentialDirectories || []).map(function(name) { return path.join(home, name); }); });
+}
+module.exports = { cleanup: cleanup, credentialPaths: credentialPaths };

package/lib/yoke/mcp-proxy.js

@@ -0,0 +1,32 @@
+// Preserve the server's JSON Schema across SDK and stdio projections.
+function validateDefinitions(definitions) {
+  var z = require('zod');
+  var names = new Set();
+  return definitions.map(function (definition) {
+    if (!definition || !/^[a-zA-Z0-9_.-]{1,128}$/.test(definition.name) || names.has(definition.name) || Object.prototype.hasOwnProperty.call(Object.prototype, definition.name)) throw new Error('Unsupported MCP tool catalog.');
+    names.add(definition.name);
+    var parsed = z.fromJSONSchema(definition.inputSchema || { type: 'object', properties: {} });
+    if (!parsed.shape) throw new Error('MCP tools must accept an object.');
+    return parsed;
+  });
+}
+function createProxy(name, definitions, invoke) {
+  var sdk = require('@anthropic-ai/claude-agent-sdk');
+  var schemas = validateDefinitions(definitions);
+  var tools = definitions.map(function (definition, index) {
+    return sdk.tool(definition.name, definition.description || definition.name, schemas[index].shape, function (args) { return invoke(definition.name, args); });
+  });
+  var server = sdk.createSdkMcpServer({ name: name, version: '1.0.0', tools: tools });
+  definitions.forEach(function (definition, index) {
+    var tool = server.instance._registeredTools[definition.name];
+    tool.inputSchema = schemas[index];
+    tool._clayInputSchema = definition.inputSchema || { type: 'object', properties: {} };
+  });
+  server.instance.server.setRequestHandler(require('@modelcontextprotocol/sdk/types.js').ListToolsRequestSchema, function () {
+    return { tools: definitions.map(function (definition) {
+      return { name: definition.name, description: definition.description, inputSchema: definition.inputSchema || { type: 'object', properties: {} } };
+    }) };
+  });
+  return server;
+}
+module.exports = { createProxy: createProxy, validateDefinitions: validateDefinitions };

package/lib/yoke/mcp-source-adapters.js

@@ -0,0 +1,91 @@
+// File-only adapters. Discovery never loads vendor code, plugins, or OAuth stores.
+var path = require('path');
+var toml = require('@iarna/toml');
+var jsonc = require('jsonc-parser');
+var yaml = require('yaml');
+var network = require('../mcp-network');
+var crypto = require('crypto');
+var ADAPTERS = {
+  claude: { user: ['.claude.json'], project: ['.mcp.json'], key: 'mcpServers' },
+  codex: { user: ['.codex/config.toml'], project: ['.codex/config.toml'], key: 'mcp_servers' },
+  kiro: { user: ['.kiro/settings/mcp.json', '.kiro/mcp.json'], project: ['.kiro/settings/mcp.json', '.kiro/mcp.json'], key: 'mcpServers', agents: '.kiro/agents' },
+  opencode: { user: ['.config/opencode/opencode.json', '.config/opencode/opencode.jsonc'], project: ['opencode.json', 'opencode.jsonc'], key: 'mcp' },
+  kimi: { user: ['.kimi-code/mcp.json', '.kimi/mcp.json'], project: ['.kimi-code/mcp.json'], key: 'mcpServers' },
+  copilot: { user: ['.copilot/mcp-config.json'], project: ['.mcp.json', '.github/mcp.json'], key: 'mcpServers' },
+  qwen: { user: ['.qwen/settings.json'], project: ['.qwen/settings.json'], key: 'mcpServers' },
+  junie: { user: ['.junie/mcp/mcp.json'], project: ['.junie/mcp/mcp.json'], key: 'mcpServers' },
+  grok: { user: ['.grok/config.toml'], project: ['.grok/config.toml'], key: 'mcp_servers' },
+  antigravity: { user: ['.gemini/config/mcp_config.json', '.gemini/antigravity-cli/mcp_config.json'], project: ['.agents/mcp_config.json'], key: 'mcpServers', plugins: '.gemini/antigravity-cli/plugins' },
+  acp: { user: [], project: [], key: 'mcpServers' },
+};
+function parse(file, content) {
+  if (file.endsWith('.md')) {
+    var match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
+    if (!match) throw new Error('Agent profile requires YAML frontmatter.');
+    var document = yaml.parseDocument(match[1]);
+    if (document.errors.length) throw new Error('Invalid agent frontmatter.');
+    return document.toJS({ maxAliasCount: 50 });
+  }
+  if (file.endsWith('.toml')) return toml.parse(content);
+  var errors = [], value = jsonc.parse(content, errors, { allowTrailingComma: true });
+  if (errors.length || !value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid MCP source format.');
+  return value;
+}
+function stringMap(value) {
+  if (!value) return {};
+  if (Array.isArray(value)) {
+    var map = {}; value.forEach(function (entry) { if (!entry || typeof entry.name !== 'string' || typeof entry.value !== 'string') throw new Error('Invalid name/value field.'); map[entry.name] = entry.value; });
+    return map;
+  }
+  if (typeof value !== 'object') throw new Error('Invalid environment or headers.');
+  Object.keys(value).forEach(function (name) { if (typeof value[name] !== 'string') throw new Error('Invalid environment or headers.'); });
+  return Object.assign({}, value);
+}
+function normalize(vendor, name, value, source) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid server definition.');
+  ['enabled', 'disabled'].forEach(function (key) { if (value[key] !== undefined && typeof value[key] !== 'boolean') throw new Error('Invalid source enablement: ' + key); });
+  if (value.oauth !== undefined && value.oauth !== true) throw new Error('Vendor OAuth policy requires reviewed Clay-owned authentication setup.');
+  var command = value.command, args = value.args || [];
+  if (vendor === 'opencode' && Array.isArray(command)) { args = command.slice(1); command = command[0]; }
+  var url = value.url || value.httpUrl || value.serverUrl;
+  if (command && url) throw new Error('Conflicting stdio and remote transport definitions.');
+  var type = value.type || value.transport || (url ? vendor === 'qwen' && !value.httpUrl ? 'sse' : 'http' : 'stdio');
+  if (type === 'local') type = 'stdio'; if (type === 'remote' || type === 'streamable-http') type = 'http';
+  if (['stdio', 'http', 'sse'].indexOf(type) < 0) throw new Error('Unsupported transport. Clay supports stdio, HTTP and SSE.');
+  if (value.headersHelper || value.oauth && (value.oauth.clientSecret || value.oauth.clientId)) throw new Error('Vendor authentication helper requires Clay-owned credential setup.');
+  var policy = require('../mcp-tool-policy').normalize(vendor, value);
+  var config = { transport: type, enabled: false, label: name, source: type === 'stdio' ? 'local' : 'url',
+    provenance: source, sourceEnabled: value.enabled === false || value.disabled === true ? false : source.scope.indexOf('plugin') === 0 ? null : true };
+  if (type === 'stdio') {
+    if (typeof command !== 'string' || !command || command.includes('\0') || !Array.isArray(args) || args.some(function (arg) { return typeof arg !== 'string' || arg.includes('\0'); })) throw new Error('Invalid stdio command or arguments.');
+    config.command = command; config.args = args; config.env = stringMap(value.env || value.environment); config.cwd = value.cwd || source.cwd;
+    if (typeof config.cwd !== 'string' || !path.isAbsolute(config.cwd)) throw new Error('Stdio working directory must be absolute.');
+  } else {
+    // Do not expand credential references during inspection.
+    config.url = network.remoteUrl(url).href; config.headers = stringMap(value.headers || value.http_headers);
+    config.envHeaders = stringMap(value.env_http_headers);
+    var bearer = value.bearer_token_env_var || value.bearerTokenEnvVar;
+    if (bearer) { config.bearerTokenEnv = bearer; config.envHeaders.Authorization = bearer; }
+  }
+  config.environmentNames = (value.env_vars || []).concat(Object.keys(config.env || {}));
+  if (value.env_vars !== undefined && !Array.isArray(value.env_vars)) throw new Error('Invalid environment allowlist.');
+  Object.assign(config, policy);
+  if (source.sourceEnabled !== undefined) config.sourceEnabled = config.sourceEnabled === false || source.sourceEnabled === false ? false : source.sourceEnabled;
+  var references = JSON.stringify([config.command, config.args, config.env, config.headers, config.url]).match(/\$\{[A-Za-z_][A-Za-z0-9_]*(?::-[^}]*)?\}|\$[A-Z_][A-Z0-9_]*|\{env:[^}]+\}|\{file:[^}]+\}|\{\{[^}]+\}\}/g) || [];
+  config.references = Array.from(new Set(references.concat(Object.values(config.envHeaders || {})).concat(value.env_vars || [])));
+  // Plugins may reference their own installed directory without reading any credential file.
+  if (source.pluginRoot) {
+    function pluginValue(value) {
+      if (typeof value === 'string') return value.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, function () { return source.pluginRoot; }).replace(/\$\{CLAUDE_PROJECT_DIR\}/g, function () { return source.cwd; });
+      if (Array.isArray(value)) return value.map(pluginValue);
+      if (value && typeof value === 'object') { var next = {}; Object.keys(value).forEach(function (key) { next[key] = pluginValue(value[key]); }); return next; }
+      return value;
+    }
+    config = pluginValue(config); config.references = config.references.filter(function (ref) { return ref !== source.pluginRoot && ref !== source.cwd; });
+  }
+  return config;
+}
+function signature(config) {
+  return crypto.createHash('sha256').update(JSON.stringify([config.transport, config.url, config.command, config.args, config.env, config.headers, config.envHeaders, config.cwd, config.disabledTools, config.enabledTools, config.toolPatterns, config.toolPrefix, config.references])).digest('hex');
+}
+module.exports = { adapters: ADAPTERS, parse: parse, normalize: normalize, signature: signature };

package/lib/yoke/mcp-source-context.js

@@ -0,0 +1,42 @@
+var path = require('path');
+var crypto = require('crypto');
+var adapters = require('./mcp-source-adapters').adapters;
+var KEYS = ['CODEX_HOME', 'CLAUDE_CONFIG_DIR', 'OPENCODE_CONFIG', 'OPENCODE_CONFIG_DIR', 'OPENCODE_CONFIG_CONTENT', 'XDG_CONFIG_HOME', 'KIMI_CODE_HOME', 'COPILOT_HOME', 'GROK_HOME', 'QWEN_HOME', 'QWEN_CODE_SYSTEM_SETTINGS_PATH', 'QWEN_CODE_SYSTEM_DEFAULTS_PATH'];
+function resolve(ctx, owner, ws, home, identity) {
+  // Only the production runtime resolver may supply mapped-user overrides.
+  var env = ctx.runtimeEnv ? ctx.runtimeEnv(owner, ws) : identity ? {} : ctx.home ? {} : process.env;
+  var selected = {};
+  KEYS.forEach(function (key) { if (env[key] !== undefined) selected[key] = env[key]; });
+  function qwenRoot(value) { if (!value) return path.join(home, '.qwen'); return path.resolve(ctx.cwd, value.replace(/^~(?=\/|$)/, home)); }
+  var roots = { copilot: path.resolve(home, env.COPILOT_HOME || '.copilot'), grok: path.resolve(home, env.GROK_HOME || '.grok'), qwen: qwenRoot(env.QWEN_HOME), codex: path.resolve(home, env.CODEX_HOME || '.codex'), claude: path.resolve(home, env.CLAUDE_CONFIG_DIR || '.claude'),
+    opencode: path.resolve(home, env.XDG_CONFIG_HOME || '.config', 'opencode'), kimi: path.resolve(home, env.KIMI_CODE_HOME || '.kimi-code') };
+  var sources = [];
+  function add(vendor, file, scope, extra) { sources.push(Object.assign({ vendor: vendor, file: file, scope: scope, cwd: ctx.cwd }, extra)); }
+  Object.keys(adapters).forEach(function (vendor) {
+    var files = adapters[vendor].user;
+    if (vendor === 'codex') files = [path.join(roots.codex, 'config.toml')];
+    if (vendor === 'claude') files = [env.CLAUDE_CONFIG_DIR ? path.join(roots.claude, '.claude.json') : path.join(home, '.claude.json')];
+    if (vendor === 'opencode') files = ['opencode.json', 'opencode.jsonc'].map(function (file) { return path.join(roots.opencode, file); });
+    if (vendor === 'copilot') files = [path.join(roots.copilot, 'mcp-config.json')];
+    if (vendor === 'grok') files = [path.join(roots.grok, 'config.toml')];
+    if (vendor === 'qwen') files = [path.join(roots.qwen, 'settings.json')];
+    if (vendor === 'kimi' && env.KIMI_CODE_HOME) files = [path.join(roots.kimi, 'mcp.json')];
+    files.forEach(function (file) { add(vendor, path.resolve(home, file), 'user'); });
+    adapters[vendor].project.forEach(function (file) { add(vendor, path.join(ctx.cwd, file), 'project'); });
+  });
+  ['opencode.json', 'opencode.jsonc'].forEach(function (file) { add('opencode', path.join(ctx.cwd, '.opencode', file), 'runtime', { configDirectory: true }); });
+  if (env.OPENCODE_CONFIG) add('opencode', path.resolve(ctx.cwd, env.OPENCODE_CONFIG), 'runtime');
+  if (env.OPENCODE_CONFIG_DIR) ['opencode.json', 'opencode.jsonc'].forEach(function (file) { add('opencode', path.resolve(ctx.cwd, env.OPENCODE_CONFIG_DIR, file), 'runtime', { configDirectory: true }); });
+  if (env.OPENCODE_CONFIG_CONTENT) add('opencode', 'runtime:OPENCODE_CONFIG_CONTENT', 'runtime-inline', { inline: env.OPENCODE_CONFIG_CONTENT });
+  return { roots: roots, policyPaths: { qwenSettings: env.QWEN_CODE_SYSTEM_SETTINGS_PATH && path.resolve(ctx.cwd, env.QWEN_CODE_SYSTEM_SETTINGS_PATH), qwenDefaults: env.QWEN_CODE_SYSTEM_DEFAULTS_PATH && path.resolve(ctx.cwd, env.QWEN_CODE_SYSTEM_DEFAULTS_PATH) }, sources: sources, fingerprint: crypto.createHash('sha256').update(JSON.stringify(selected)).digest('hex') };
+}
+function priority(source) {
+  if (source.scope === 'runtime-inline') return 80;
+  if (source.scope === 'configured') return 70;
+  if (source.scope === 'runtime') return source.configDirectory ? 65 : 30;
+  if (source.scope === 'local') return 60;
+  if (source.scope === 'project') return 50 + (source.vendor === 'copilot' && path.basename(source.file) === '.mcp.json' ? 1 : 0);
+  if (source.scope === 'project-ancestor') return 40 + source.file.split(path.sep).length * 0.01 + (path.basename(source.file) === '.mcp.json' ? 0.001 : 0);
+  return source.scope.indexOf('plugin') === 0 ? 10 : 20;
+}
+module.exports = { resolve: resolve, priority: priority };