@vectros-ai/mcp-server 0.12.0 → 0.14.0

package/dist/cli.js

@@ -87,6 +87,7 @@ __export(api_exports, {
   TooManyRequestsError: () => TooManyRequestsError,
   TruncationWarningEvent: () => TruncationWarningEvent,
   UnauthorizedError: () => UnauthorizedError,
+  UserExistsResponse: () => UserExistsResponse,
   UserRequest: () => UserRequest,
   UserResponse: () => UserResponse,
   auth: () => auth_exports,
@@ -763,6 +764,14 @@ var TruncationWarningEvent;
     ContextWindowBudget: "context_window_budget"
   };
 })(TruncationWarningEvent || (TruncationWarningEvent = {}));
+var UserExistsResponse;
+((UserExistsResponse2) => {
+  UserExistsResponse2.Status = {
+    Active: "ACTIVE",
+    Suspended: "SUSPENDED",
+    Pending: "PENDING"
+  };
+})(UserExistsResponse || (UserExistsResponse = {}));
 var UserRequest;
 ((UserRequest2) => {
   UserRequest2.Status = {
@@ -2455,7 +2464,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/admin/access-log");
   }
   /**
-   * Lists all of your scoped API keys (`ssk_*`) across both your live and test environments. Revoked keys are excluded. Requires the `keys:r` scope.
+   * Lists your scoped API keys (`ssk_*`) in your credential's own environment — a live key lists live keys, a test key lists test keys. Revoked keys are excluded. Requires the `keys:r` scope.
    *
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
    *
@@ -2506,7 +2515,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/admin/keys/scoped");
   }
   /**
-   * Creates a scoped API key (an `ssk_*` secret) that inherits its permissions from an existing access profile in your account. The call is idempotent on the combination of tenant, context, user, and key name: re-issuing the same request returns the existing key WITHOUT re-disclosing its raw secret. The raw key is returned ONLY in this response — store it securely, as it cannot be retrieved again. Requires the `keys:c` scope.
+   * Creates a scoped API key (an `ssk_*` secret) that inherits its permissions from an existing access profile in your account. The call is idempotent on the combination of tenant, context, user, and key name: re-issuing the same request returns the existing key WITHOUT re-disclosing its raw secret. The raw key is returned ONLY in this response — store it securely, as it cannot be retrieved again. Requires the `keys:c` scope. If you use a scoped credential, `keys:c` alone is not sufficient: because the minted key is durably bound to the profile you name, the profile's effective scopes may not exceed your own, and you may only mint against a profile whose `identityOverrides` values your own identity holds. A root API key (`sk_`) is exempt from both bounds.
    *
    * @param {Vectros.CreateScopedKeyRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -2838,7 +2847,7 @@ var AuthClient = class {
     );
   }
   /**
-   * Creates a new access profile under the given app context. This call is idempotent by `principalId`: if a profile with the same `principalId` already exists, the existing profile is returned (with status 200) instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing profile was returned) tells the two apart. To overwrite an existing profile's `scopes`/`roleId`, `identityOverrides`, and `status` instead of returning it unchanged, set `?upsert=true` (this also requires the `profiles:u` scope). You must provide exactly one of `scopes` (an inline list of scopes) or `roleId` (a reference to a role); supplying both, or neither, is rejected. `identityOverrides` is keyed by ownership namespace in `scope:<namespace>` form — `scope:org` and `scope:client` for the reserved namespaces, or any namespace you have registered — and may name at most two; any other key (including the account identifier or `userId`) is rejected. If you use a scoped credential, the profile's effective scopes may not exceed your own; a root API key (`sk_`) is exempt. Requires the `profiles:c` scope.
+   * Creates a new access profile under the given app context. This call is idempotent by `principalId`: if a profile with the same `principalId` already exists, the existing profile is returned (with status 200) instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing profile was returned) tells the two apart. To overwrite an existing profile's `scopes`/`roleId`, `identityOverrides`, and `status` instead of returning it unchanged, set `?upsert=true` (this also requires the `profiles:u` scope, and applies the same `identityOverrides` bounds the update endpoint documents — a scoped credential may not repoint or clear an identity value it does not itself hold). You must provide exactly one of `scopes` (an inline list of scopes) or `roleId` (a reference to a role); supplying both, or neither, is rejected. `identityOverrides` is keyed by ownership namespace in `scope:<namespace>` form — `scope:org` and `scope:client` for the reserved namespaces, or any namespace you have registered — and may name at most two; any other key (including the account identifier or `userId`) is rejected. If you use a scoped credential, the profile's effective scopes may not exceed your own; a root API key (`sk_`) is exempt. Requires the `profiles:c` scope.
    *
    * @param {Vectros.CreateAccessProfileRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -3256,11 +3265,12 @@ var AuthClient = class {
     );
   }
   /**
-   * Updates an access profile. This is a partial update: any field you omit (or send as null) keeps its existing value. A profile must reference either inline `scopes` or a `roleId`, never both — so setting `scopes` clears any `roleId`, and setting `roleId` clears any inline `scopes`. The `contextId` and `principalId` are immutable. Status changes (for example active to suspended) take effect within about five minutes. If you use a scoped credential, the profile's effective scopes may not exceed your own; a root API key (`sk_`) is exempt. Requires the `profiles:u` scope.
+   * Updates an access profile. This is a partial update: any field you omit (or send as null) keeps its existing value. A profile must reference either inline `scopes` or a `roleId`, never both — so setting `scopes` clears any `roleId`, and setting `roleId` clears any inline `scopes`. The `contextId` and `principalId` are immutable. Status changes (for example active to suspended) take effect within about five minutes. If you use a scoped credential, the profile's effective scopes may not exceed your own, and its `identityOverrides` are bounded twice: you may only set a value your own identity holds, and you may only change or clear a value the profile already holds if that value is yours as well. Repointing or clearing another principal's established identity therefore returns 403. A root API key (`sk_`) is exempt. If you set `roleId`, it must reference a role that already exists in this context. Requires the `profiles:u` scope.
    *
    * @param {Vectros.UpdateAccessProfileRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.TooManyRequestsError}
@@ -3307,6 +3317,8 @@ var AuthClient = class {
     }
     if (_response.error.reason === "status-code") {
       switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
         case 403:
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
@@ -3329,7 +3341,7 @@ var AuthClient = class {
     );
   }
   /**
-   * Deletes an access profile. Within about five minutes (the access-profile cache lifetime), token minting for this principal in this context will be denied. Requires the `profiles:d` scope.
+   * Deletes an access profile. Within about five minutes (the access-profile cache lifetime), token minting for this principal in this context will be denied. If you use a scoped credential and the profile carries `identityOverrides`, you may only delete it when you hold those values yourself — deleting a profile removes its identity, so the same bound applies as when clearing it. A profile with no `identityOverrides` is unaffected, and a root API key (`sk_`) is exempt. Requires the `profiles:d` scope.
    *
    * @param {Vectros.DeleteAccessProfileRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -3998,6 +4010,254 @@ var AuthClient = class {
     }
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/usage");
   }
+  /**
+   * Retrieves a single registered issuer by issuerId. Requires a root API key or the bootstrap's provisioning capability.
+   *
+   * @param {Vectros.GetIssuerRequest} request
+   * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.NotFoundError}
+   *
+   * @example
+   *     await client.auth.getIssuer({
+   *         issuerId: "auth0-prod"
+   *     })
+   */
+  getIssuer(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__getIssuer(request, requestOptions));
+  }
+  async __getIssuer(request, requestOptions) {
+    const { issuerId } = request;
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        `v1/auth/issuers/${url_exports.encodePathParam(issuerId)}`
+      ),
+      method: "GET",
+      headers: _headers,
+      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 404:
+          throw new NotFoundError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/auth/issuers/{issuerId}");
+  }
+  /**
+   * Deregisters a trusted third-party IdP issuer. Requires a root API key or the bootstrap's provisioning capability. Unconditional — unlike some other registry deletes on this API, this does not check for or block on any downstream reference. Any user account already created via this issuer (by a prior self-signup or accepted invite) is NOT deleted or modified, but that user can no longer obtain a NEW token this way once you deregister the issuer — every `POST /v1/auth/token/exchange` call against it will 404, with no distinction between an unknown issuer and one you just deregistered. Register a replacement issuer, or restore this one, before your users' current tokens expire if you want their access to continue uninterrupted.
+   *
+   * @param {Vectros.DeleteIssuerRequest} request
+   * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
+   *
+   * @example
+   *     await client.auth.deleteIssuer({
+   *         issuerId: "auth0-prod"
+   *     })
+   */
+  deleteIssuer(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__deleteIssuer(request, requestOptions));
+  }
+  async __deleteIssuer(request, requestOptions) {
+    const { issuerId } = request;
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        `v1/auth/issuers/${url_exports.encodePathParam(issuerId)}`
+      ),
+      method: "DELETE",
+      headers: _headers,
+      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: void 0, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 404:
+          throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(
+      _response.error,
+      _response.rawResponse,
+      "DELETE",
+      "/v1/auth/issuers/{issuerId}"
+    );
+  }
+  /**
+   * Returns the issuers registered in your tenant. Requires a root API key or the bootstrap's provisioning capability. Returns a `{data, nextCursor}` envelope.
+   *
+   * @param {Vectros.ListIssuersRequest} request
+   * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.ForbiddenError}
+   *
+   * @example
+   *     await client.auth.listIssuers()
+   */
+  listIssuers(request = {}, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__listIssuers(request, requestOptions));
+  }
+  async __listIssuers(request = {}, requestOptions) {
+    const { startFrom, limit } = request;
+    const _queryParams = {
+      startFrom,
+      limit
+    };
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        "v1/auth/issuers"
+      ),
+      method: "GET",
+      headers: _headers,
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/auth/issuers");
+  }
+  /**
+   * Registers a trusted third-party IdP issuer that BYO-IdP token exchange (`POST /v1/auth/token/exchange`) may accept a `subject_token` from. Requires a root API key or the CLI bootstrap's provisioning capability — never an ordinary partner-grantable scope. Idempotent by `issuerId` within your tenant; the `(issuer, audience)` pair must not already be registered by a different issuerId/tenant.
+   *
+   * @param {Vectros.IssuerRequest} request
+   * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.TooManyRequestsError}
+   *
+   * @example
+   *     await client.auth.registerIssuer({
+   *         issuerId: "auth0-prod",
+   *         issuer: "https://your-tenant.us.auth0.com/",
+   *         jwksUri: "https://your-tenant.us.auth0.com/.well-known/jwks.json",
+   *         audience: "https://api.your-app.example.com",
+   *         contextId: "casework"
+   *     })
+   */
+  registerIssuer(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__registerIssuer(request, requestOptions));
+  }
+  async __registerIssuer(request, requestOptions) {
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        "v1/auth/issuers"
+      ),
+      method: "POST",
+      headers: _headers,
+      contentType: "application/json",
+      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      requestType: "json",
+      body: request,
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/auth/issuers");
+  }
   /**
    * Returns the identity bound to your credential — your account, principal type, key id, and scope details — so you can confirm who you are authenticated as and that the credential is valid. MCP clients use this to render "signed in as ..." in a chat UI without a separate identity endpoint.
    *
@@ -4183,7 +4443,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/auth/token");
   }
   /**
-   * Invite a new member to one of your app contexts by email. Creates a pending user with a pre-resolved access profile (their permissions on accept) and signs an invitation token. This call is idempotent on the combination of context and email: re-inviting the same email in the same context rotates the token and resends the invitation rather than creating a duplicate. Returns HTTP 201 on a new invite or a successful resend. Returns 409 if that email already belongs to an active or suspended member of the app context, or already has an identity elsewhere in your account (an email can currently belong to only one tenant per account, i.e. your test and live environments cannot share an email). When `sendEmail` is false, the response includes the raw token and a ready-to-use accept link so you can deliver the invitation through your own email provider. Requires the `admin:users` scope.
+   * Invite a new member to one of your app contexts by email. Creates a pending user with a pre-resolved access profile (their permissions on accept) and signs an invitation token. This call is idempotent on the combination of context and email: re-inviting the same email in the same context rotates the token and resends the invitation rather than creating a duplicate — this requires the `users:r` and `users:u` scopes in addition to `users:c`, because resending rotates a credential on an existing invitation and invalidates any link already sent. Without them the collision returns 409 instead, with no invitation details and no change to the outstanding invitation. Returns HTTP 201 on a new invite or a successful resend. Returns 409 if that email already belongs to an active or suspended member of the app context, or already has an identity elsewhere in your account (an email can currently belong to only one tenant per account, i.e. your test and live environments cannot share an email). When `sendEmail` is false, the response includes the raw token and a ready-to-use accept link so you can deliver the invitation through your own email provider. Requires the `users:c` scope.
    *
    * @param {Vectros.CreateInviteRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4254,7 +4514,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/users/invite");
   }
   /**
-   * Resend an outstanding invitation, identified by its email and app context. Rotates the invitation token and extends its expiry, then (when `sendEmail` is true) re-delivers the email. Rotating the token invalidates any previously issued link for this invitation, so only the newest link works. The invitee's pending permissions are left unchanged. Requires the `admin:users` scope.
+   * Resend an outstanding invitation, identified by its email and app context. Rotates the invitation token and extends its expiry, then (when `sendEmail` is true) re-delivers the email. Rotating the token invalidates any previously issued link for this invitation, so only the newest link works. The invitee's pending permissions are left unchanged. Because this rotates a credential on an existing invitation, it requires the `users:c`, `users:r` and `users:u` scopes.
    *
    * @param {Vectros.CreateInviteRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4321,6 +4581,72 @@ var AuthClient = class {
     }
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/users/invite/resend");
   }
+  /**
+   * RFC 8693 OAuth 2.0 Token Exchange. Trades a JWT issued by a third-party identity provider you've registered (`POST /v1/auth/issuers`) for a Vectros `st_*` scoped bearer token — no Vectros credential required to call this endpoint. The exchanged token's scope is resolved entirely server-side from the matched user's access profile; this endpoint accepts no caller-supplied scope, resource, or audience parameter (RFC 8693 §2.1's `resource`/`audience`/`scope` are not used in v1 — the registered `(issuer, audience)` pair alone pins the target tenant and app context). On a first-time login (no existing Vectros identity for this subject), two opt-in binding paths exist: `invite_token` (a `PENDING` sub-user invitation), and — if the registration declares one or more self-signup policies — `signup_type` (a brand-new user is created and bound to the policy's configured role). If `invite_token` is present at all, it is the ONLY path tried — a failed invite never falls through to self-signup. Neither field is required for a subject with an existing identity. Uses the OAuth-standard error envelope (`{"error":..., "error_description":...}`, RFC 6749 §5.2), NOT this API's usual `{"message":...}` shape — its client is generic OAuth tooling, not the Vectros SDK.
+   *
+   * @param {Vectros.TokenExchangeRequest} request
+   * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.UnauthorizedError}
+   * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
+   *
+   * @example
+   *     await client.auth.exchangeToken({
+   *         grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+   *         subject_token: "subject_token",
+   *         subject_token_type: "urn:ietf:params:oauth:token-type:jwt"
+   *     })
+   */
+  exchangeToken(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__exchangeToken(request, requestOptions));
+  }
+  async __exchangeToken(request, requestOptions) {
+    const _headers = mergeHeaders(this._options?.headers, requestOptions?.headers);
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        "v1/auth/token/exchange"
+      ),
+      method: "POST",
+      headers: _headers,
+      contentType: "application/json",
+      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      requestType: "json",
+      body: request,
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 401:
+          throw new UnauthorizedError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 404:
+          throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/auth/token/exchange");
+  }
 };
 var ComplianceClient = class {
   constructor(options) {
@@ -4588,7 +4914,7 @@ var DocumentsClient = class {
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         scope: "group:eng-team",
    *         folderId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
-   *         startFrom: "doc_prev123"
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   listDocuments(request = {}, requestOptions) {
@@ -4898,6 +5224,7 @@ var DocumentsClient = class {
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
@@ -4945,6 +5272,8 @@ var DocumentsClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
@@ -4975,7 +5304,7 @@ var DocumentsClient = class {
    *         field: "po_number",
    *         value: "PO-1001",
    *         prefix: "PO-2024",
-   *         startFrom: "550e8400-e29b-41d4-a716-446655440000",
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl",
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         scope: "org:6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    *     })
@@ -5351,7 +5680,7 @@ var FoldersClient = class {
    *         parentFolderId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         scope: "group:eng-team",
-   *         startFrom: "fld_prev123"
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   listFolders(request = {}, requestOptions) {
@@ -5528,6 +5857,7 @@ var FoldersClient = class {
    * @param {Vectros.UpdateFolderRequest} request
    * @param {FoldersClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
@@ -5572,6 +5902,8 @@ var FoldersClient = class {
     }
     if (_response.error.reason === "status-code") {
       switch (_response.error.statusCode) {
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 429:
@@ -5654,6 +5986,7 @@ var FoldersClient = class {
    * @param {FoldersClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
@@ -5701,6 +6034,8 @@ var FoldersClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
@@ -5788,7 +6123,8 @@ var IdentityClient = class {
    *
    * @example
    *     await client.identity.listEntities({
-   *         namespace: "team"
+   *         namespace: "team",
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   listEntities(request, requestOptions) {
@@ -6552,7 +6888,7 @@ var IdentityClient = class {
    * @example
    *     await client.identity.listUsers({
    *         externalId: "usr_12345",
-   *         startFrom: "550e8400-e29b-41d4-a716-446655440000",
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl",
    *         type: "person_v1",
    *         field: "team",
    *         value: "engineering",
@@ -6733,11 +7069,12 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/users/{id}");
   }
   /**
-   * Updates mutable fields on an existing user (such as email, status, payload, or schema binding). The `type` field is immutable after creation. This endpoint also activates an invited user: a PUT that moves a PENDING user to ACTIVE and carries `inviteToken`, `externalSubject`, and `emailVerifiedAttestation=true` completes the invitation. Requires the `users:u` scope.
+   * Updates mutable fields on an existing user (such as email, status, payload, or schema binding). The `type` field is immutable after creation, and `email` cannot be changed while an invitation to that user is still outstanding — revoke the invitation, or invite the new address instead. This endpoint also activates an invited user: a PUT that moves a PENDING user to ACTIVE and carries `inviteToken`, `externalSubject`, and `emailVerifiedAttestation=true` completes the invitation. Requires the `users:u` scope.
    *
    * @param {Vectros.UpdateUserRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
@@ -6782,6 +7119,8 @@ var IdentityClient = class {
     }
     if (_response.error.reason === "status-code") {
       switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 429:
@@ -6915,6 +7254,69 @@ var IdentityClient = class {
     }
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/users/lookup");
   }
+  /**
+   * Answers "does a user with this email hold an ACTIVE access profile in this app context" — a narrow existence check, not a general lookup. `exists` is false for a member whose access to this context has been suspended, not only for a member who was never granted it. The answer is scoped to the `contextId` you supply: it does not reveal whether the email exists elsewhere in your tenant or account, only whether it belongs to an active member of the named context. Returns `{exists, userId, status}` — never the full user record — so a caller asking "does X exist" cannot receive that user's payload/schema binding/etc. as a side effect. Useful for resolving an email you were handed (for example, by an org-admin adding an existing member to another org) to a `userId`, without paging through the full context membership. Requires the `users:r` scope.
+   *
+   * @param {Vectros.UserExistsByEmailRequest} request
+   * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
+   *
+   * @example
+   *     await client.identity.userExistsByEmail({
+   *         email: "user@example.com",
+   *         contextId: "myapp"
+   *     })
+   */
+  userExistsByEmail(request = {}, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__userExistsByEmail(request, requestOptions));
+  }
+  async __userExistsByEmail(request = {}, requestOptions) {
+    const { email, contextId } = request;
+    const _queryParams = {
+      email,
+      contextId
+    };
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        "v1/users/exists-by-email"
+      ),
+      method: "GET",
+      headers: _headers,
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/users/exists-by-email");
+  }
   /**
    * Returns the audit trail of changes to a user, most recent first. Identity history is always recorded and always available. Sensitive field values are redacted in every historical version. Returns a page in the `{data, nextCursor}` envelope. Requires the `users:r` scope.
    *
@@ -7429,7 +7831,7 @@ var RecordsClient = class {
    *         folderId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         scope: "group:eng-team",
-   *         startFrom: "550e8400-e29b-41d4-a716-446655440000"
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   listRecords(request = {}, requestOptions) {
@@ -7617,6 +8019,7 @@ var RecordsClient = class {
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
@@ -7665,6 +8068,8 @@ var RecordsClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
@@ -7746,6 +8151,7 @@ var RecordsClient = class {
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
@@ -7796,6 +8202,8 @@ var RecordsClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
@@ -7813,7 +8221,15 @@ var RecordsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PATCH", "/v1/records/{id}");
   }
   /**
-   * Finds records by the value of a lookup field declared on the type's schema. Provide exactly one lookup mode: `value` (exact match), `from`+`to` (inclusive range, ascending by value), or `prefix` (string fields only, ascending). Range and prefix lookups are not supported on a sensitive field, because its value is stored as a blind index and has no sortable order. An exact-`value` lookup on a sensitive field is also rejected on this GET endpoint — the value must not appear in the URL — so use the `POST /v1/records/lookup` body variant for sensitive fields. Results are paginated: set `limit` for the page size and pass the returned `nextCursor` back as `startFrom` for the next page. Requires the `records:r:<type>` scope.
+   * Finds records by the value of a lookup field declared on the type's schema. Provide exactly one lookup mode: `value` (exact match), `from`+`to` (inclusive range, ascending by value), or `prefix` (string fields only, ascending). Range and prefix lookups are not supported on a sensitive field, because its value is stored as a blind index and has no sortable order. An exact-`value` lookup on a sensitive field is also rejected on this GET endpoint — the value must not appear in the URL — so use the `POST /v1/records/lookup` body variant for sensitive fields.
+   *
+   * A `value` lookup can additionally be narrowed to a window of the lookup field's **sort key** using `sortFrom` and/or `sortTo` (inclusive) — for example, one session's records created since a timestamp. The sort key is whatever the schema declares as that lookup's `sortBy` (`createdAt` by default, `lastUpdated`, or another field), and bounds are given in that field's own units — epoch milliseconds for the two timestamp options. **Records that have no value for the sorted field are never included in a bounded window** — they are ordered ahead of every record that does have one, and a `sortFrom`/`sortTo` window only ever selects from records carrying a value. The sorted field does not have to be `required`.
+   *
+   * Narrowing is available on any lookup field your schema declares for fast equality lookup, and on `externalId` — which is always ordered by creation time, so its bounds are epoch milliseconds whatever the schema says. It is rejected (`400`) for a field declared with `rangeEnabled`, for a field declared beyond the schema's fast-lookup budget, for a lookup whose `sortBy` names a sensitive field (a sensitive value is stored as a blind index and has no order), and for a window whose start is after its end. Ownership fields are not lookup fields on this endpoint at all — see the `field` parameter.
+   *
+   * While paging a narrowed lookup, keep every other parameter identical. The cursor is valid only for the exact query that returned it — changing `order`, `sortFrom`, `sortTo`, or dropping them altogether, is rejected rather than silently resumed at a position that means something different in the new query.
+   *
+   * Results are paginated: set `limit` for the page size and pass the returned `nextCursor` back as `startFrom` for the next page. **Keep paging until `nextCursor` is null** — a page can come back empty or shorter than `limit` while more results remain, so an empty page is not the end of the results. Requires the `records:r:<type>` scope.
    *
    * @param {Vectros.LookupRecordsRequest} request
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -7825,22 +8241,40 @@ var RecordsClient = class {
    *         type: "intake_form",
    *         field: "email",
    *         value: "jane@example.com",
+   *         values: ["open"],
    *         prefix: "jane",
-   *         startFrom: "550e8400-e29b-41d4-a716-446655440000"
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   lookupRecords(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__lookupRecords(request, requestOptions));
   }
   async __lookupRecords(request, requestOptions) {
-    const { type: type_, field, value, from: from_, to, prefix, startFrom, limit, includePayload, order } = request;
+    const {
+      type: type_,
+      field,
+      value,
+      values,
+      from: from_,
+      to,
+      prefix,
+      sortFrom,
+      sortTo,
+      startFrom,
+      limit,
+      includePayload,
+      order
+    } = request;
     const _queryParams = {
       type: type_,
       field,
       value,
+      values,
       from: from_,
       to,
       prefix,
+      sortFrom,
+      sortTo,
       startFrom,
       limit,
       includePayload,
@@ -7884,7 +8318,7 @@ var RecordsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/records/lookup");
   }
   /**
-   * Body-based equivalent of `GET /v1/records/lookup`. Use this when looking up by a sensitive field: the value travels in the request body (and is blind-indexed server-side) instead of in the URL query string, so it never lands in access, CDN, or proxy logs. The GET variant rejects an exact-value lookup on a sensitive field and directs you here. Non-sensitive exact-value, range (`from`+`to`), and prefix lookups also work here. Returns the same `{data, nextCursor}` envelope and uses the same pagination as the GET variant. Requires the `records:r:<type>` scope.
+   * Body-based equivalent of `GET /v1/records/lookup`. Use this when looking up by a sensitive field: the value travels in the request body (and is blind-indexed server-side) instead of in the URL query string, so it never lands in access, CDN, or proxy logs. The GET variant rejects an exact-value lookup on a sensitive field and directs you here. Non-sensitive exact-value, range (`from`+`to`), and prefix lookups also work here, as does narrowing a `value` lookup by the field's sort key with `sortFrom`/`sortTo` — see the GET variant for what the sort key is and when narrowing by it is available. Returns the same `{data, nextCursor}` envelope and uses the same pagination as the GET variant; keep paging until `nextCursor` is null rather than stopping on an empty page. Requires the `records:r:<type>` scope.
    *
    * @param {Vectros.RecordLookupRequest} request
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -8079,7 +8513,7 @@ var SchemasClient = class {
    *         scope: "org:6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    *         surface: "document",
    *         recordType: "intake_form",
-   *         startFrom: "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   listSchemas(request = {}, requestOptions) {
@@ -8283,6 +8717,7 @@ var SchemasClient = class {
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
@@ -8331,6 +8766,8 @@ var SchemasClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 429:
@@ -8636,15 +9073,15 @@ function warnOnSuboptimalKey(key, log) {
   } else if (key.prefix === "st") {
     log.warn(
       { prefix: key.prefix, env: key.env },
-      "short-lived token (st_*) will expire mid-session (1h default, 24h max). For long-running MCP installs, prefer a long-lived ssk_* key."
+      "short-lived token (st_*) will expire mid-session (1h max). For long-running MCP installs, prefer a long-lived ssk_* key."
     );
   }
 }
 
 // src/build-info.ts
 var BUILD_INFO = {
-  mcpServer: true ? "0.12.0" : "dev",
-  sdk: true ? "0.37.0" : "dev"
+  mcpServer: true ? "0.14.0" : "dev",
+  sdk: true ? "0.39.0" : "dev"
 };
 function formatBuildInfo() {
   return `vectros-mcp-server ${BUILD_INFO.mcpServer} (sdk ${BUILD_INFO.sdk})`;
@@ -8687,7 +9124,9 @@ async function resolveIdentity({
   const derived = {
     status: "ok",
     environment: deriveEnvironment(environment),
-    principalType: derivePrincipalType(apiKey)
+    principalType: derivePrincipalType(apiKey),
+    mcpServerVersion: BUILD_INFO.mcpServer,
+    sdkVersion: BUILD_INFO.sdk
   };
   if (!apiKey || !environment) {
     log.debug({ component: "identity", mode: "derived-only" }, "identity derived (no fetch)");
@@ -8715,7 +9154,13 @@ async function resolveIdentity({
       );
     }
   }
-  const merged = { ...derived, ...extended, status: "ok" };
+  const merged = {
+    ...derived,
+    ...extended,
+    status: "ok",
+    mcpServerVersion: derived.mcpServerVersion,
+    sdkVersion: derived.sdkVersion
+  };
   log.debug(
     {
       component: "identity",
@@ -9037,14 +9482,23 @@ var import_zod2 = require("zod");
 function pageItems(page) {
   return page.data ?? [];
 }
+var MAX_PAGES = 100;
+var MAX_ROWS = 1e6;
 async function drainPages(fetchPage) {
   const all = [];
   let startFrom;
+  let pages = 0;
   for (; ; ) {
     const page = await fetchPage(startFrom);
-    if (page.data?.length) all.push(...page.data);
+    pages++;
+    if (page.data?.length) for (const item of page.data) all.push(item);
     const next = page.nextCursor;
     if (!next) break;
+    if (pages > MAX_PAGES || all.length > MAX_ROWS) {
+      throw new Error(
+        `drainPages: exceeded the runaway guard (${all.length} rows over ${pages} pages, limits ${MAX_ROWS}/${MAX_PAGES}) without the cursor going null. Refusing to return a partial result \u2014 the backend may be returning empty pages with a live cursor.`
+      );
+    }
     startFrom = next;
   }
   return all;
@@ -9055,14 +9509,23 @@ var MCP_DEFAULT_LIMIT2 = 3;
 var MCP_MAX_LIMIT2 = 100;
 var inputSchema2 = {
   type: import_zod2.z.string().min(1, "type (record type) is required").describe('Record type / schema name (e.g. "patient", "clinical_note").'),
-  // Lookup-mode args — provide `field` plus EXACTLY ONE of: value | from+to | prefix.
+  // Lookup-mode args — provide `field` plus EXACTLY ONE of: value | values | from+to | prefix.
   field: import_zod2.z.string().optional().describe(
-    'Lookup mode: name of the lookup-indexed field to query by. `externalId` is always queryable \u2014 e.g. `{type:"control", field:"externalId", value:"ctrl-scoped-key"}` finds the record you created under that externalId. (record_get / record_update also accept externalId directly.)'
+    'Lookup mode: name of the lookup-indexed field to query by. `externalId` is always queryable \u2014 e.g. `{type:"control", field:"externalId", value:"ctrl-scoped-key"}` finds the record you created under that externalId. (record_get / record_update also accept externalId directly.) For a SCHEMA-declared composite lookup \u2014 check list_schemas\' lookupFields for a fieldNames entry, not any two fields you pick \u2014 give those field names comma-joined in the declared order (e.g. "status,area"). Use `values` to match on several of those fields at once, or `value` to match on just the FIRST field named (equivalent to a one-element `values`); range/prefix are not valid on a composite field.'
+  ),
+  value: import_zod2.z.string().optional().describe(
+    "Lookup mode (equality): exact-match value for `field`. Also valid when `field` names a SCHEMA-declared composite lookup \u2014 matches just the first named field, grouping by the rest (equivalent to `values` with one entry)."
+  ),
+  values: import_zod2.z.array(import_zod2.z.string()).min(1).max(3).optional().describe(
+    'Lookup mode (composite equality): only valid against a lookup the SCHEMA declares over several fields together (a fieldNames entry in list_schemas \u2014 you cannot combine two ordinary single-field lookups this way). One value per field, in the order the schema declares them (e.g. field="status,area", values=["open","billing"]). Mutually exclusive with `value`; a single-element array is exactly `value` written uniformly. Supplying FEWER values than the lookup declares is allowed \u2014 as long as they\'re a leading run of its fields \u2014 and returns records grouped by the fields left unspecified; `order` then sorts within each group, not across them. Record lookups only (not documents/users/entities).'
   ),
-  value: import_zod2.z.string().optional().describe("Lookup mode (equality): exact-match value for `field`."),
   from: import_zod2.z.string().optional().describe("Lookup mode (range): inclusive lower bound; requires `to`. Non-sensitive fields only."),
   to: import_zod2.z.string().optional().describe("Lookup mode (range): inclusive upper bound; requires `from`."),
   prefix: import_zod2.z.string().optional().describe("Lookup mode (prefix): match values starting with this. String, non-sensitive fields only."),
+  sortFrom: import_zod2.z.string().optional().describe(
+    "Lookup mode (equality/composite only): inclusive lower bound on the lookup field's sort key, narrowing a `value`/`values` match to a window instead of paging the whole match. Give the bound in the sort field's own units (epoch milliseconds for `createdAt`/`lastUpdated`). With `values`, requires every value be supplied (no grouping) for one continuous ordering. Not valid with `from`/`to`/`prefix`."
+  ),
+  sortTo: import_zod2.z.string().optional().describe("Lookup mode (equality/composite only): inclusive upper bound on the sort key; pairs with `sortFrom`."),
   order: import_zod2.z.enum(["asc", "desc"]).optional().describe(
     "Lookup mode: sort direction by the looked-up field. `asc` (default) or `desc` \u2014 use `desc` with a range/prefix lookup to get the most-recent / highest values first (e.g. latest-N). Ignored in list mode."
   ),
@@ -9079,54 +9542,106 @@ var inputSchema2 = {
 var recordQuery = ({ client, log }) => ({
   name: "record_query",
   title: "Record query (list or lookup)",
-  description: "Query structured records of a given type. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Works on sensitive fields too.\n  \u2022 List by type: omit `field`; optionally filter by `userId` or `scope` (`namespace:value`).\nReturns a `{ data, nextCursor }` page: `data` holds up to `limit` records (default 3, max 100 \u2014 raise it in one call when you can accept the payload), and a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page. Mode is auto-detected from the arguments present.",
+  description: "Query structured records of a given type. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `field` plus exactly one of `value` (exact), `values` (exact, composite \u2014 one value per field; a single-element array is the same as `value`), `from`+`to` (range), or `prefix`. `values` with more than one entry, or a comma-joined `field`, ONLY works for a lookup the schema itself declared over several fields together \u2014 check list_schemas' lookupFields for a fieldNames entry, then pass those field names comma-joined as `field`; `from`/`to`/`prefix` are not valid there. Works on sensitive fields too. Optionally narrow an exact match to a window with `sortFrom`/`sortTo`.\n  \u2022 List by type: omit `field`; optionally filter by `userId` or `scope` (`namespace:value`).\nReturns a `{ data, nextCursor }` page: `data` holds up to `limit` records (default 3, max 100 \u2014 raise it in one call when you can accept the payload), and a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page. A composite lookup given fewer than its full field count returns records grouped by the unspecified fields, ordered within each group. Mode is auto-detected from the arguments present.",
   inputSchema: inputSchema2,
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT2;
     const type = args.type;
     const field = args.field;
     const value = args.value;
+    const values = args.values;
     const from = args.from;
     const to = args.to;
     const prefix = args.prefix;
+    const sortFrom = args.sortFrom;
+    const sortTo = args.sortTo;
     const startFrom = args.startFrom;
+    if (!field && (value !== void 0 || values !== void 0 || from !== void 0 || to !== void 0 || prefix !== void 0 || sortFrom !== void 0 || sortTo !== void 0)) {
+      return toolError(
+        "record_query",
+        new Error(
+          "'value'/'values'/'from'/'to'/'prefix'/'sortFrom'/'sortTo' require 'field' \u2014 without it, list mode runs and silently ignores them. Pass 'field' to run a lookup, or drop these to list by type."
+        )
+      );
+    }
     try {
       let page;
       if (field) {
+        const fieldNames = field.split(",").map((f) => f.trim()).filter(Boolean);
+        const normalizedField = fieldNames.join(",");
+        const isCompositeField = fieldNames.length > 1;
         const hasEquality = value !== void 0;
+        const hasComposite = values !== void 0;
         const hasRange = from !== void 0 || to !== void 0;
         const hasPrefix = prefix !== void 0;
-        const modes = Number(hasEquality) + Number(hasRange) + Number(hasPrefix);
+        const modes = Number(hasEquality) + Number(hasComposite) + Number(hasRange) + Number(hasPrefix);
         if (modes === 0) {
           return toolError(
             "record_query",
             new Error(
-              `lookup on field '${field}' needs one of: 'value' (exact), 'from'+'to' (range), or 'prefix'.`
+              `lookup on field '${field}' needs one of: 'value' (exact), 'values' (composite exact), 'from'+'to' (range), or 'prefix'.`
             )
           );
         }
         if (modes > 1) {
           return toolError(
             "record_query",
-            new Error("'value', 'from'/'to', and 'prefix' are mutually exclusive \u2014 provide exactly one.")
+            new Error(
+              "'value', 'values', 'from'/'to', and 'prefix' are mutually exclusive \u2014 provide exactly one."
+            )
           );
         }
         if (hasRange && !(from !== void 0 && to !== void 0)) {
           return toolError("record_query", new Error("range lookup requires both 'from' and 'to'."));
         }
+        if (isCompositeField && (hasRange || hasPrefix)) {
+          return toolError(
+            "record_query",
+            new Error(
+              `'field' names ${fieldNames.length} fields ('${normalizedField}') \u2014 a composite lookup is exact-match only ('value' or 'values'), not 'from'/'to'/'prefix'.`
+            )
+          );
+        }
+        if (hasComposite && values.length > fieldNames.length) {
+          return toolError(
+            "record_query",
+            new Error(
+              `'values' has ${values.length} entries but 'field' names only ${fieldNames.length} field(s) ('${normalizedField}') \u2014 supply at most one value per field, in order (fewer only as a leading run).`
+            )
+          );
+        }
+        if (sortFrom !== void 0 || sortTo !== void 0) {
+          if (!(hasEquality || hasComposite)) {
+            return toolError(
+              "record_query",
+              new Error("'sortFrom'/'sortTo' narrow a 'value' or 'values' match only \u2014 not 'from'/'to'/'prefix'.")
+            );
+          }
+          if (hasComposite && values.length < fieldNames.length) {
+            return toolError(
+              "record_query",
+              new Error(
+                `'sortFrom'/'sortTo' with 'values' requires a value for every field named in 'field' (got ${values.length} of ${fieldNames.length}) \u2014 a partial/grouped match has no single continuous ordering to window.`
+              )
+            );
+          }
+        }
         page = await client.records.lookupRecordsByBody({
           type,
-          field,
+          field: normalizedField,
           value,
+          values,
           from,
           to,
           prefix,
+          sortFrom,
+          sortTo,
           order: args.order,
           startFrom,
           limit
         });
         log.debug(
-          { tool: "record_query", mode: "lookup", type, field, returned: pageItems(page).length },
+          { tool: "record_query", mode: "lookup", type, field: normalizedField, returned: pageItems(page).length },
           "record_query lookup ok"
         );
       } else {
@@ -10065,7 +10580,7 @@ var inputSchema18 = {
 var currentIdentity = ({ log, apiKey, environment }) => ({
   name: "current_identity",
   title: "Current identity (tenant + principal scope)",
-  description: "Describe the credential the MCP server is operating under. Returns tenantId, environment (staging|production), principalType (root_key|scoped_key|token), principalKeyId, principalLabel, and (for scoped credentials) allowedActions plus dataScope \u2014 the credential's reach as { userId, scopes[] }, where each scope is a `namespace:value` string (e.g. \"org:<uuid>\"). Use this when the user asks 'what can you do here?' or 'what tenant am I in?'. Calls GET /v1/ping under the hood.",
+  description: "Describe the credential the MCP server is operating under. Returns tenantId, environment (staging|production), principalType (root_key|scoped_key|token), principalKeyId, principalLabel, and (for scoped credentials) allowedActions plus dataScope \u2014 the credential's reach as { userId, scopes[] }, where each scope is a `namespace:value` string (e.g. \"org:<uuid>\"). Also reports mcpServerVersion (this server's own package version) and sdkVersion (the bundled @vectros-ai/sdk version) so a caller can tell what build it's talking to. Use this when the user asks 'what can you do here?', 'what tenant am I in?', or 'what version is this?'. Calls GET /v1/ping under the hood.",
   inputSchema: inputSchema18,
   handler: async () => {
     try {
@@ -10543,7 +11058,7 @@ var identityResource = ({ log, apiKey, environment }) => ({
   name: "identity",
   uri: "vectros://identity",
   title: "Current identity (tenant + principal scope)",
-  description: "The tenant + principal scope the MCP server is authenticated as. Returns the same payload as the `current_identity` tool: status, tenantId, environment, principalType, principalKeyId, principalLabel, and (for scoped credentials) allowedActions + dataScope ({ userId, scopes[] }). The /v1/ping backing call ships this extended shape today.",
+  description: "The tenant + principal scope the MCP server is authenticated as. Returns the same payload as the `current_identity` tool: status, tenantId, environment, principalType, principalKeyId, principalLabel, (for scoped credentials) allowedActions + dataScope ({ userId, scopes[] }), plus mcpServerVersion and sdkVersion (this build's own version and the bundled @vectros-ai/sdk version). The /v1/ping backing call ships the extended shape today; the version fields are always client-derived.",
   mimeType: "application/json",
   read: async () => {
     const identity = await resolveIdentity({ log, apiKey, environment });