@yanlinglabs/winter-agent-runtime 0.0.29 → 0.0.30

package/dist/{index-8jgwp1px.js → index-9s68t0pd.js}

@@ -1,3 +1,11 @@
+import {
+  mcpOAuthTokenAccount2,
+  MCP_OAUTH_EXPIRY_SKEW_MS2,
+  MCP_OAUTH_SESSION_CACHE_MS2,
+  readTokenRecordLenient,
+  refreshMcpOAuthToken2
+} from "./index-z6s3r4xm.js";
+
 // src/process-groups.ts
 var live = new Map;
 var listeners = new Set;
@@ -109,8 +117,117 @@ function toWireElicitContent(content) {
   return out;
 }
 
+// src/mcp-auth/session-provider.ts
+class McpNeedsAuthError extends Error {
+  serverName;
+  constructor(serverName, why, hint) {
+    super(`MCP server "${serverName}" needs sign-in (${why}). ${hint}`);
+    this.name = "McpNeedsAuthError";
+    this.serverName = serverName;
+  }
+}
+
+class McpAuthRefreshUnavailableError extends Error {
+  constructor(serverName) {
+    super(`MCP server "${serverName}": its sign-in could not be refreshed right now (the authorization server did not answer); reconnect it later`);
+    this.name = "McpAuthRefreshUnavailableError";
+  }
+}
+function createSessionAuthProvider(opts) {
+  const { serverName, oauth } = opts;
+  const account = mcpOAuthTokenAccount2(opts.serverUrl);
+  const now = oauth.now ?? Date.now;
+  let cached;
+  let refreshing;
+  const needsAuth = (why) => new McpNeedsAuthError(serverName, why, oauth.signInHint(serverName));
+  let refreshedGeneration;
+  const usable = (record) => {
+    if (record.expiresAt === undefined)
+      return true;
+    const margin = record.refreshToken !== undefined && record.generation !== refreshedGeneration ? MCP_OAUTH_EXPIRY_SKEW_MS2 : 0;
+    return record.expiresAt - now() > margin;
+  };
+  async function read(force) {
+    if (!force && cached !== undefined && now() - cached.readAt < MCP_OAUTH_SESSION_CACHE_MS2 && (cached.record === null || usable(cached.record)))
+      return cached.record;
+    const record = await readTokenRecordLenient(oauth.store, account);
+    cached = { record, readAt: now() };
+    return record;
+  }
+  async function ask(generation, stepUpScope) {
+    const request = { server: serverName, account, generation, ...stepUpScope !== undefined ? { stepUpScope } : {} };
+    if (oauth.askHost !== undefined) {
+      const answer = await oauth.askHost(request).catch(() => ({ ok: false, reason: "transient" }));
+      if (answer !== "unhandled")
+        return answer;
+      if (oauth.hostOwnsRefresh === true)
+        return { ok: false, reason: "transient" };
+    }
+    if (oauth.hostOwnsRefresh === true)
+      return { ok: false, reason: "transient" };
+    const result = await refreshMcpOAuthToken2({ account, store: oauth.store, generation, ...stepUpScope !== undefined ? { stepUpScope } : {}, ...oauth.fetch !== undefined ? { fetch: oauth.fetch } : {}, ...oauth.now !== undefined ? { now: oauth.now } : {} });
+    return result.ok ? { ok: true } : result;
+  }
+  function refresh(generation) {
+    refreshing ??= ask(generation).finally(() => {
+      refreshing = undefined;
+    });
+    return refreshing;
+  }
+  async function refreshed(record) {
+    if (record.refreshToken === undefined)
+      throw needsAuth("the stored token has expired and there is no refresh token");
+    const answer = await refresh(record.generation);
+    if (!answer.ok) {
+      if (answer.reason === "needs_auth")
+        throw needsAuth("the sign-in could not be refreshed");
+      throw new McpAuthRefreshUnavailableError(serverName);
+    }
+    const next = await read(true);
+    if (next === null || next.generation === record.generation)
+      throw needsAuth("the refreshed sign-in was not found");
+    refreshedGeneration = next.generation;
+    return next;
+  }
+  async function current() {
+    const record = await read(false);
+    if (record === null)
+      return;
+    if (usable(record))
+      return record.accessToken;
+    return (await refreshed(record)).accessToken;
+  }
+  return {
+    token: current,
+    async preflight() {
+      await current();
+    },
+    async onUnauthorized() {
+      const before = cached?.record ?? null;
+      const record = await read(true);
+      if (record === null)
+        throw needsAuth("the server requires a sign-in");
+      if (before === null || record.accessToken !== before.accessToken)
+        return;
+      await refreshed(record);
+    },
+    async reportInsufficientScope(scope) {
+      const record = await read(true).catch(() => null);
+      if (record === null || scope === undefined || scope.trim() === "")
+        return;
+      await ask(record.generation, scope).catch(() => {
+        return;
+      });
+    }
+  };
+}
+function mcpSignInHint(brand, serverName) {
+  const cli = brand.homeDirName.replace(/^\./, "");
+  return `Sign in with \`${cli} mcp login ${serverName}\` (or ${brand.productName} Settings -> MCP), then reconnect the server.`;
+}
+
 // src/mcp/client.ts
-import { Client, ProtocolError, ProtocolErrorCode, SdkError, SdkErrorCode, SdkHttpError, SseError, UnauthorizedError, UnsupportedProtocolVersionError } from "@modelcontextprotocol/client";
+import { Client, InsufficientScopeError, ProtocolError, ProtocolErrorCode, SdkError, SdkErrorCode, SdkHttpError, SseError, UnauthorizedError, UnsupportedProtocolVersionError } from "@modelcontextprotocol/client";
 
 // src/mcp/transports/stdio.ts
 import { spawn } from "node:child_process";
@@ -261,19 +378,22 @@ function buildStdioTransport(cfg, cwd) {
 
 // src/mcp/transports/http.ts
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+var refusingRedirectsFetch = (url, init) => fetch(url, { ...init, redirect: "error" });
 function buildHttpTransport(cfg, opts = {}) {
   const requestInit = { ...cfg.headers !== undefined ? { headers: cfg.headers } : {}, ...opts.refuseRedirects === true ? { redirect: "error" } : {} };
   const transport = new StreamableHTTPClientTransport(new URL(cfg.url), {
-    ...Object.keys(requestInit).length > 0 ? { requestInit } : {}
+    ...Object.keys(requestInit).length > 0 ? { requestInit } : {},
+    ...opts.authProvider !== undefined ? { authProvider: opts.authProvider, fetch: refusingRedirectsFetch } : {}
   });
   return transport;
 }
 
 // src/mcp/transports/sse.ts
 import { SSEClientTransport } from "@modelcontextprotocol/client";
-function buildSseTransport(cfg) {
+function buildSseTransport(cfg, opts = {}) {
   const transport = new SSEClientTransport(new URL(cfg.url), {
-    ...cfg.headers !== undefined ? { requestInit: { headers: cfg.headers } } : {}
+    ...cfg.headers !== undefined ? { requestInit: { headers: cfg.headers } } : {},
+    ...opts.authProvider !== undefined ? { authProvider: opts.authProvider, fetch: refusingRedirectsFetch } : {}
   });
   return transport;
 }
@@ -310,6 +430,12 @@ function toSdkNegotiationMode(mode) {
 function classifyConnectError(err, facts = { transportClosed: false, pinned: false }) {
   if (err instanceof McpConnectError2)
     return err;
+  if (err instanceof McpNeedsAuthError)
+    return new McpConnectError2("needs_auth", err.message);
+  if (err instanceof McpAuthRefreshUnavailableError)
+    return new McpConnectError2("auth_refresh_failed", err.message);
+  if (err instanceof InsufficientScopeError)
+    return new McpConnectError2("needs_auth", "the server requires additional permission (403 insufficient_scope); sign in again to grant it", 403);
   if (err instanceof UnauthorizedError)
     return new McpConnectError2("needs_auth", err.message);
   if (err instanceof SdkError && err.code === SdkErrorCode.RequestTimeout)
@@ -367,7 +493,7 @@ function autoProbeTimeoutMs(connectTimeoutMs) {
   return Math.max(1, Math.min(AUTO_PROBE_TIMEOUT_CAP_MS, Math.floor(connectTimeoutMs / 3)));
 }
 function retriesAsLegacy(err) {
-  if (err.code === "needs_auth" || err.code === "spawn_failed" || err.code === "version_mismatch")
+  if (err.code === "needs_auth" || err.code === "auth_refresh_failed" || err.code === "spawn_failed" || err.code === "version_mismatch")
     return false;
   return err.httpStatus !== 401 && err.httpStatus !== 403;
 }
@@ -428,10 +554,11 @@ async function connectOnce(opts, mode, connectTimeoutMs, probeTimeoutMs) {
         throw new McpConnectError2("spawn_failed", `mcp client: server "${name}" is configured as type "sdk" but no in-process server instance was supplied to connectMcpServer`);
       }
       transport = await buildSdkTransport(opts.inProcessServer);
-    } else if (config.type === "http") {
-      transport = buildHttpTransport(config, opts.refuseHttpRedirects === true ? { refuseRedirects: true } : {});
-    } else if (config.type === "sse") {
-      transport = buildSseTransport(config);
+    } else if (config.type === "http" || config.type === "sse") {
+      if (opts.auth !== undefined)
+        await boundedPreflight(opts.auth, connectTimeoutMs);
+      const authProvider = opts.auth !== undefined ? { token: () => opts.auth.token(), onUnauthorized: () => opts.auth.onUnauthorized() } : undefined;
+      transport = config.type === "http" ? buildHttpTransport(config, { ...opts.refuseHttpRedirects === true ? { refuseRedirects: true } : {}, ...authProvider !== undefined ? { authProvider } : {} }) : buildSseTransport(config, authProvider !== undefined ? { authProvider } : {});
     } else {
       if (opts.cwd === undefined) {
         throw new McpConnectError2("spawn_failed", `mcp client: stdio server "${name}" has no session cwd to start in; it is never started in the host process's cwd`);
@@ -516,10 +643,13 @@ async function connectOnce(opts, mode, connectTimeoutMs, probeTimeoutMs) {
       }
     };
   } catch (err) {
+    const scopeChallenge = insufficientScopeOf(err);
+    if (scopeChallenge !== undefined && opts.auth !== undefined)
+      await opts.auth.reportInsufficientScope(scopeChallenge.requiredScope).catch(() => {});
     const stderrTail = transport instanceof WinterStdioTransport ? transport.stderrTail.trim() : "";
     const facts = { transportClosed: transport instanceof WinterStdioTransport && transport.exitedOnItsOwn, pinned: typeof mode === "object" };
     try {
-      await transport.close();
+      await transport?.close();
     } catch {}
     const classified = classifyConnectError(err, facts);
     if (stderrTail === "" || classified.message.includes(stderrTail))
@@ -529,5 +659,34 @@ async function connectOnce(opts, mode, connectTimeoutMs, probeTimeoutMs) {
 ${stderrTail}`, classified.httpStatus);
   }
 }
+function boundedPreflight(auth, timeoutMs) {
+  let timer;
+  const outer = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new McpConnectError2("timeout", `mcp client: the sign-in check exceeded ${timeoutMs}ms`)), timeoutMs);
+    timer.unref?.();
+  });
+  return Promise.race([auth.preflight(), outer]).finally(() => {
+    if (timer !== undefined)
+      clearTimeout(timer);
+  });
+}
+function insufficientScopeOf(err) {
+  for (let e = err, depth = 0;e !== undefined && e !== null && depth < 4; e = e.cause, depth++) {
+    if (e instanceof InsufficientScopeError)
+      return e;
+  }
+  return;
+}
+function classifyMcpAuthFailure(err) {
+  for (let e = err, depth = 0;e !== undefined && e !== null && depth < 4; e = e.cause, depth++) {
+    if (e instanceof InsufficientScopeError)
+      return "insufficient_scope";
+    if (e instanceof McpNeedsAuthError || e instanceof UnauthorizedError)
+      return "needs_auth";
+    if (e instanceof SdkHttpError && e.status === 401)
+      return "needs_auth";
+  }
+  return;
+}
 
-export { trackProcessGroup, liveProcessGroups, onProcessGroupChange, createElicitationAsker2, McpConnectError2, resolveVersionNegotiation2, connectMcpServer2 };
+export { trackProcessGroup, liveProcessGroups, onProcessGroupChange, createElicitationAsker2, createSessionAuthProvider, mcpSignInHint, McpConnectError2, resolveVersionNegotiation2, connectMcpServer2, insufficientScopeOf, classifyMcpAuthFailure };

package/dist/index-bgeqc7ax.js

@@ -0,0 +1,52 @@
+import {
+  evaluateMcpAuthUrl2,
+  isLoopbackMcpServer
+} from "./index-z6s3r4xm.js";
+
+// src/mcp-auth/config.ts
+var OAUTH_KEYS = new Set(["clientId", "clientSecretRef", "callbackPort", "authServerMetadataUrl", "scopes"]);
+var SECRET_REF_KEYS = new Set(["kind"]);
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateMcpOAuthConfig2(oauth, serverUrl) {
+  if (!isPlainObject(oauth))
+    return "MCP server config 'oauth' must be an object";
+  for (const key of Object.keys(oauth)) {
+    if (key === "clientSecret")
+      return `MCP server config 'oauth.clientSecret' is refused: a client secret never lives in a config -- store it in the Keychain (the host's sign-in door) and mark it with 'oauth.clientSecretRef': { kind: "keychain" }`;
+    if (!OAUTH_KEYS.has(key))
+      return `MCP server config 'oauth' has an unknown key ${JSON.stringify(key)} (expected clientId, clientSecretRef, callbackPort, authServerMetadataUrl, scopes)`;
+  }
+  const { clientId, clientSecretRef, callbackPort, authServerMetadataUrl, scopes } = oauth;
+  if (clientId !== undefined && (typeof clientId !== "string" || clientId.trim() === ""))
+    return "MCP server config 'oauth.clientId' must be a non-empty string";
+  if (clientSecretRef !== undefined) {
+    if (clientId === undefined)
+      return "MCP server config 'oauth.clientSecretRef' needs 'oauth.clientId': a secret belongs to a pre-registered client";
+    if (!isPlainObject(clientSecretRef))
+      return `MCP server config 'oauth.clientSecretRef' must be { kind: "keychain" }`;
+    for (const key of Object.keys(clientSecretRef)) {
+      if (!SECRET_REF_KEYS.has(key))
+        return `MCP server config 'oauth.clientSecretRef' has the key ${JSON.stringify(key)}, which is refused: it is { kind: "keychain" } only -- the secret's Keychain account is derived from the server URL, never named by a config`;
+    }
+    if (clientSecretRef.kind !== "keychain")
+      return `MCP server config 'oauth.clientSecretRef.kind' must be "keychain"`;
+  }
+  if (callbackPort !== undefined && (typeof callbackPort !== "number" || !Number.isInteger(callbackPort) || callbackPort < 1 || callbackPort > 65535)) {
+    return "MCP server config 'oauth.callbackPort' must be an integer port (1-65535)";
+  }
+  if (authServerMetadataUrl !== undefined) {
+    if (typeof authServerMetadataUrl !== "string")
+      return "MCP server config 'oauth.authServerMetadataUrl' must be a URL string";
+    const verdict = evaluateMcpAuthUrl2(authServerMetadataUrl, { allowLoopback: serverUrl !== undefined && isLoopbackMcpServer(serverUrl) });
+    if (!verdict.ok)
+      return `MCP server config 'oauth.authServerMetadataUrl' is refused: ${verdict.reason}`;
+  }
+  if (scopes !== undefined && (!Array.isArray(scopes) || scopes.some((s) => typeof s !== "string" || s === "" || /\s/.test(s)))) {
+    return "MCP server config 'oauth.scopes' must be an array of scope tokens (non-empty, no whitespace)";
+  }
+  return;
+}
+
+export { validateMcpOAuthConfig2 };

package/dist/{index-eyddzcgs.js → index-wsfqsrh5.js}

@@ -9,14 +9,14 @@ import {
   resolveEngineSession2,
   resolveProductionWinterHome2,
   resolveProductionStoreHome
-} from "./index-jz5d90c6.js";
+} from "./index-51673qbw.js";
 import {
   registerDefaultChildEngineFactory,
   loadResumedChain,
   buildProductionWiring,
   withAutoSkillPermissions,
   restoreChildRoster
-} from "./index-gmxxtqpe.js";
+} from "./index-9df1q7j4.js";
 
 // src/embedded.ts
 import { splitFrames, encodeFrame } from "@yanlinglabs/winter-agent-sdk";