@uipath/delegate-sdk 1.202.0 → 1.203.0-preview.20260924122926

package/README.md

@@ -45,7 +45,7 @@ import { runLoginFlow } from '@uipath/delegate-sdk';
 const auth = await runLoginFlow({ env: 'production' });   // 'alpha' | 'staging' | 'production'
 ```
 
-`runLoginFlow` runs OAuth PKCE in your browser and saves to `~/.aria/sdk-auth.json` (`env`, or an explicit `baseUrl`, is required — there is no default cloud; `tenant` picks a tenant by name, `silent: true` suppresses the console output). The browser is sent back to a loopback listener on `http://localhost:8055/oidc/login`; when that port is busy the login falls back to 42042, then 8104 (the three callbacks registered for the built-in client — 8104 is `uip login`'s fixed port, so it is tried last):
+`runLoginFlow` runs OAuth PKCE in your browser and saves to `~/.aria/sdk-auth.json` (`env` for a UiPath cloud, or `baseUrl` for an [Automation Suite or other self-hosted deployment](#automation-suite-and-other-self-hosted-deployments), is required — there is no default deployment; `tenant` picks a tenant by name, `silent: true` suppresses the console output). The browser is sent back to a loopback listener on `http://localhost:8055/oidc/login`; when that port is busy the login falls back to 42042, then 8104 (the three callbacks registered for the built-in client — 8104 is `uip login`'s fixed port, so it is tried last):
 
 ```json
 {
@@ -73,9 +73,34 @@ saveAuthData(await switchTenant(auth, 'Finance'));
 
 **Following a saved login**: `readSavedAuthRecord(filePath)` reads one file as `SdkAuthData`, without network calls or fallback to another login; missing or invalid records return `null`. Capture `grantIdentity(auth)` when the host starts, compare later reads with `sameGrantIdentity(pinned, grantIdentity(candidate))`, and pass the pin as `refreshAccessToken(auth, { authFilePath, pinnedIdentity })`. Refresh runs under the SDK's cross-process lock and checks the supplied credentials, a peer's rotation adopted from the file, and the refreshed grant against the pin before returning or saving anything. Without a pin, it uses the supplied credentials' identity. Unknown client/subject fields remain compatible with legacy records; org and tenant must always match. Hosts do not need to snapshot or restore the auth file after a rejected refresh: a foreign grant is never written, and the login's pending marker stays set so the consumed refresh token is not replayed (it needs a new login).
 
+### Automation Suite and other self-hosted deployments
+
+Anything that is not one of the named clouds — Automation Suite, Dedicated, Public Sector — is signed into by URL instead of by name:
+
+```ts
+const auth = await runLoginFlow({ baseUrl: 'https://automationsuite.contoso.com' });
+```
+
+(`delegate-cli login --url https://automationsuite.contoso.com` from the CLI.) A tenant path or a trailing `/identity_` is accepted and reduced to the origin, so the URL you already have to hand works. Non-`https` URLs and URLs with embedded credentials are refused.
+
+**Requirements**
+
+- **Automation Suite 26.10 or later with the Delegate service installed.** Older deployments are refused at login (see below).
+- **An identity client the deployment accepts.** The built-in client is a registration on the UiPath clouds; if the deployment rejects it with `invalid_client`, register your own external application there and set `UIPATH_CLIENT_ID` — see the next section for the redirect URIs and scopes to register.
+- **A trusted certificate.** If the deployment uses a private certificate authority, point Node at it with `NODE_EXTRA_CA_CERTS=/path/to/ca.pem`. Do not disable certificate verification: sign-in and token requests carry credentials.
+
+**What login checks, and when.** Two questions, deliberately asked at two different moments:
+
+1. *Before the browser opens*, `GET {url}/identity_/.well-known/openid-configuration` — proving a UiPath Identity is mounted there, and yielding the authorize/token endpoints the flow then uses. All three advertised URLs must sit on the origin you named, so a host that merely proxies a UiPath-shaped document cannot redirect the sign-in elsewhere. This fails closed: nothing reaches a browser until it passes.
+2. *After the token exchange and tenant selection*, an authenticated `GET {url}/{org}/{tenant}/delegate_/v1/config` — the same read-only request `delegate-cli models` and `runHealthCheck` make. On Automation Suite (`IS_AUTOMATION_SUITE: true`) the backend must list `delegate` in `SUPPORTED_SHELL_APPS`; the key is absent on pre-26.10 images by construction, so its absence is the version gate (the Orchestrator version cannot tell those images apart). A deployment whose Delegate service is missing, unreachable or too old is refused before anything is written to disk. A UiPath cloud is never asked.
+
+`runLoginFlow({ skipEnvCheck: true })` (`delegate-cli login --skip-env-check`) skips both and assumes the `{url}/identity_/connect/...` endpoint shape. It exists for a deployment that puts discovery behind an ingress rule, or serves Identity from a different origin than the one being signed into; it also gives up the diagnosis when something is genuinely wrong.
+
+Everything after login is deployment-agnostic: org/tenant lookup, token refresh, and the backend URL all use the same `{base}/{org}/{tenant}/<service>_` routing the clouds use. The one exception is the interop sidecar's OIDC issuer, which the SDK pins for you — see [Computer use & interop lifecycle](#computer-use--interop-lifecycle).
+
 ### Using your own identity app
 
-By default the SDK authenticates as a built-in UiPath **public** client (PKCE, no secret): `Orchestrator.HYOA.CLI`, the same client `uip login` uses, whose loopback callback is registered on alpha, staging and production. To use your own identity app instead, override the client id — and, for a confidential app, the secret:
+By default the SDK authenticates as a built-in UiPath **public** client (PKCE, no secret): `Orchestrator.HYOA.CLI`, the same client `uip login` uses, whose loopback callback is registered on alpha, staging and production. A self-hosted deployment may not have that registration, in which case the token exchange fails with `invalid_client` and the error says so. To use your own identity app instead, override the client id — and, for a confidential app, the secret:
 
 ```bash
 export UIPATH_CLIENT_ID=<your-client-id>
@@ -117,9 +142,11 @@ When `autoSpawnInterop` is on (and no `interopUrl` was supplied), the SDK spawns
 |---|---|---|
 | default | fresh per invocation | killed on exit |
 | `keepInteropAlive: true` | reuse PID-file process, else spawn | left running |
-| `new InteropProcess().stop({ force: true })` | — | force-kill PID-file process |
+| `new InteropProcess().stop({ force: true })` | — | force-kill every PID-file process |
+
+PID files: `~/.delegate-sdk/interop.pid` for the UiPath clouds, plus one `interop-<hash>.pid` per self-hosted deployment. Stale entries (dead process or `/health` not responding) are cleaned up automatically.
 
-PID file: `~/.delegate-sdk/interop.pid`. Stale entries (dead process or `/health` not responding) are cleaned up automatically.
+**OIDC issuer on a self-hosted deployment**: the interop resolves its trusted token issuers *once at startup*. Given no `--base-url` it trusts only the three UiPath clouds, so an interop started that way rejects every call made with an Automation Suite token — as a 401, with nothing pointing at the cause. The SDK therefore starts it with `--base-url=<deployment origin>` whenever `auth.baseUrl` is a self-hosted deployment, and records it in a PID file of that deployment's own. Interops for different deployments therefore run side by side: starting a session against one never stops the interop another live session is using. A cloud login deliberately keeps the default three issuers, so a reused interop still works across an alpha→staging switch. `runHealthCheck` spawns its interop with the same pin.
 
 **Turn-policy snapshots**: the interop denies governed endpoints (filesystem, shell, Office, PDF, computer use) unless the request carries an `X-Delegate-Policy-Snapshot` header naming a pre-registered snapshot. The SDK handles this automatically whenever an interop is engaged: it registers a full-access global snapshot per agent turn (and one ambient snapshot for interop calls made outside any turn) and attaches the header. Registration needs an organization id from the auth provider; without one, turns fail with "Local access policy could not be selected".
 

package/dist/index.mjs

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/dist/index.mjs
-size: 59729033 bytes
-sha256: aa7570400618057a20ea929fbb30aa70fad5f202034e29a47aba98a1a0a5e96d
+size: 60680376 bytes
+sha256: 4798f78e74d85d630e4c42b71419e635ef92a797b5c07decaadfcd632427c464

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/delegate-sdk",
-  "version": "1.202.0",
+  "version": "1.203.0-preview.20260924122926",
   "description": "UiPath Delegate SDK - Programmatic agent interface",
   "license": "Apache-2.0",
   "type": "commonjs",
@@ -50,9 +50,9 @@
     "zod-to-json-schema": "^3.25.1"
   },
   "optionalDependencies": {
-    "@uipath/delegate-runtime-darwin-arm64": "1.202.0",
-    "@uipath/delegate-runtime-win32-x64": "1.202.0",
-    "@uipath/delegate-runtime-linux-x64": "1.202.0"
+    "@uipath/delegate-runtime-darwin-arm64": "1.203.0-preview.20260924122926",
+    "@uipath/delegate-runtime-win32-x64": "1.203.0-preview.20260924122926",
+    "@uipath/delegate-runtime-linux-x64": "1.203.0-preview.20260924122926"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",