@mcp-abap-adt/connection 9.3.0 → 9.3.1

package/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [9.3.1] - 2026-09-27
+
+### Fixed
+
+- **Over HTTP, a request that is not stateful no longer reaches the stateful
+  context.** `sap-contextid` names the context a `LOCK` opens, and SAP routes any
+  request that carries it into that context — session header or none. The wire
+  sent the whole jar on every request, so a "stateless" `PUT` after a `LOCK` ran
+  in the lock's context. Measured 2026-09-27 on one connection, a package locked,
+  written and unlocked twice:
+  - E19 (BASIS 816): the second `PUT` answered 400 PAK/058 "Package … is already
+    locked" — the first save was still in that context's `CL_PACKAGE` buffer, and
+    a delete on the same connection was refused the same way;
+  - E98 (BASIS 756): every `PUT` answered 423 "Resource … is not locked (invalid
+    lock handle)".
+
+  With the cookie kept to the stateful requests, both systems wrote twice and
+  deleted on the same connection. That is Eclipse ADT's split too: its trace
+  shows one stateful session for `LOCK` and `UNLOCK` alone and every other
+  request, the `PUT` included, outside it. The jar still holds the cookie, so
+  the `UNLOCK` that follows reaches the context holding the lock.
+
+  The cookie is filtered on the header as it finally goes out, not only on
+  the jar: the connection's CSRF and 401 retries write the whole jar into the
+  request's own `Cookie`, and a caller can spell that header in lower case.
+  Either way, a non-stateful request does not carry the context.
+
+### Changed
+
+- **The session type is the wire's to express, not the connection's.**
+  `setSessionType('stateful')` now marks each request `stateful: true` on
+  `IAdtTransportRequest` instead of writing `x-sap-adt-sessiontype` into its
+  headers.
+  - `HttpTransport` adds `x-sap-adt-sessiontype: stateful` and `sap-contextid`
+    to stateful requests only (overridable through `sessionTypeHeaders()`;
+    `LegacyOnPremHttpTransport` sends no header, as before). The legacy wire
+    decides stateful before it drops a header the caller wrote, so a caller
+    that asks for the session that way — `AdtClassLegacy` — keeps its context
+    cookie, and its `UNLOCK` still reaches the lock.
+  - `RfcTransport` sends no session header, which is what Eclipse's JCo trace
+    shows.
+
+  A request whose caller wrote the header themselves is still treated as
+  stateful.
+
+  **What a consumer does:** nothing, through the connectors. A custom
+  `IAdtTransport` reads `request.stateful` where it used to find the header.
+
 ## [9.3.0] - 2026-09-26
 
 ### Changed
@@ -1783,7 +1831,8 @@ const connection = createAbapConnection(config, logger);
 - JWT token refresh now properly handles connection errors (401/403 during initial connect)
 - Permission errors (403 with "ExceptionResourceNoAccess") no longer trigger JWT refresh loops
 - Proper separation: base class handles HTTP/session, concrete classes handle auth-specific errors
-[Unreleased]: https://github.com/fr0ster/mcp-abap-connection/compare/v9.3.0...HEAD
+[Unreleased]: https://github.com/fr0ster/mcp-abap-connection/compare/v9.3.1...HEAD
+[9.3.1]: https://github.com/fr0ster/mcp-abap-connection/compare/v9.3.0...v9.3.1
 [9.3.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v9.2.2...v9.3.0
 [9.2.2]: https://github.com/fr0ster/mcp-abap-connection/compare/v9.2.1...v9.2.2
 [9.2.1]: https://github.com/fr0ster/mcp-abap-connection/compare/v9.2.0...v9.2.1

package/README.md

@@ -429,7 +429,11 @@ See [MIGRATION-4.0.md](./docs/MIGRATION-4.0.md).
 
 ### Stateful Sessions
 
-For operations that require session state (e.g., object modifications), you can enable stateful sessions:
+Enable stateful mode for requests that need the ABAP context, such as LOCK and
+UNLOCK. Switch to stateless for GET and PUT between them: a lock handle does
+not require the write itself to run in the lock’s context. Authentication
+cookies and the CSRF token remain available in both modes. See the
+[Stateful Session Guide](./docs/STATEFUL_SESSION_GUIDE.md) for transport behavior.
 
 ```typescript
 import {
@@ -450,18 +454,18 @@ const connection = new AdtOnPremConnector(
 );
 await connection.connect();
 
-// Enable stateful session mode (adds x-sap-adt-sessiontype: stateful header)
+// Enable the stateful HTTP context (session header and context cookie)
 connection.setSessionType("stateful");
 
-// Make requests - SAP will maintain session state
-await connection.makeAdtRequest({
-  method: "POST",
-  url: "/sap/bc/adt/objects/domains",
-  data: { /* domain data */ },
-  timeout: getTimeout("default"),
-});
+// Send the LOCK request here, then leave its context for GET / PUT.
+connection.setSessionType("stateless");
+
+// Send GET / PUT with the lock handle here.
+// Return to the same context when sending UNLOCK.
+connection.setSessionType("stateful");
+// Send UNLOCK here, then restore the default mode.
+connection.setSessionType("stateless");
 
-// Note: Session state persistence is handled by @mcp-abap-adt/auth-broker package
 ```
 
 ### Custom Logger

package/dist/connection/AbstractAbapConnection.d.ts

@@ -126,7 +126,9 @@ declare abstract class AbstractAbapConnection implements AbapConnection, ISessio
     transport: IAdtTransport, logger: ILogger | null, sessionId?: string);
     /**
      * Set session type (stateful or stateless)
-     * Controls whether x-sap-adt-sessiontype: stateful header is added to requests
+     * Marks the requests that follow as `stateful` for the transport, which says
+     * so on its own wire (over HTTP: `x-sap-adt-sessiontype: stateful` and the
+     * context cookie; over RFC: nothing)
      * - stateful: SAP maintains session state between requests (locks, transactions)
      * - stateless: Each request is independent
      *

package/dist/connection/AbstractAbapConnection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/AbstractAbapConnection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AbstractAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/AbstractAbapConnection.ts"],"names":[],"mappings":"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"}

package/dist/connection/AbstractAbapConnection.js

@@ -170,7 +170,9 @@ class AbstractAbapConnection {
     }
     /**
      * Set session type (stateful or stateless)
-     * Controls whether x-sap-adt-sessiontype: stateful header is added to requests
+     * Marks the requests that follow as `stateful` for the transport, which says
+     * so on its own wire (over HTTP: `x-sap-adt-sessiontype: stateful` and the
+     * context cookie; over RFC: nothing)
      * - stateful: SAP maintains session state between requests (locks, transactions)
      * - stateless: Each request is independent
      *
@@ -857,11 +859,11 @@ class AbstractAbapConnection {
             !hasHeader(requestHeaders, 'x-sap-adt-profiling')) {
             requestHeaders['X-sap-adt-profiling'] = this.profilingRequest;
         }
-        // And this one really is the session's: it says how the server should treat
-        // the request, which is the only one of the three that varies with the mode.
-        if (this.sessionMode === 'stateful') {
-            requestHeaders['x-sap-adt-sessiontype'] = 'stateful';
-        }
+        // The session mode is NOT a header here. How a request asks for the
+        // stateful session is the wire's: HTTP says it with
+        // `x-sap-adt-sessiontype: stateful` and the context cookie, RFC with
+        // neither. It travels as `stateful` on the request below, and each
+        // transport expresses it its own way.
         // Add auth headers (these MUST NOT be overridden)
         Object.assign(requestHeaders, await this.getAuthHeaders());
         // Read once: the wire is asked what it holds, and the same value is what
@@ -909,6 +911,7 @@ class AbstractAbapConnection {
             // `unknown` on the caller's options, a record on the seam: the two
             // transports serialise a query differently and both need the pairs.
             params: params,
+            stateful: this.sessionMode === 'stateful',
         };
         if (data !== undefined) {
             requestConfig.data = data;

package/dist/connection/HttpTransport.d.ts

@@ -21,6 +21,15 @@
 import { type AgentOptions } from 'node:https';
 import type { ILogger } from '../logger.js';
 import type { IAdtEstablishContext, IAdtSessionContext, IAdtTransport, IAdtTransportRequest, IAdtTransportResponse } from './IAdtTransport.js';
+/**
+ * Whether the request runs in the stateful session: marked so by the
+ * connection, or — kept for callers that still write it themselves — carrying
+ * the session header already.
+ *
+ * Exported for the wires that rewrite a request before sending it: the
+ * verdict has to be taken on the request as the caller made it.
+ */
+export declare function isStatefulRequest(request: IAdtTransportRequest): boolean;
 export declare class HttpTransport implements IAdtTransport {
     private readonly agentOptions;
     protected readonly logger: ILogger | null;
@@ -141,6 +150,13 @@ export declare class HttpTransport implements IAdtTransport {
      * looking like it carried a session.
      */
     private dress;
+    /**
+     * How this wire asks for the stateful session: `x-sap-adt-sessiontype:
+     * stateful`, as Eclipse sends on its `LOCK` and `UNLOCK` over HTTP. A wire
+     * whose system is hurt by the header overrides this (BASIS 7.40, see
+     * `LegacyOnPremHttpTransport`).
+     */
+    protected sessionTypeHeaders(): Record<string, string>;
     /** A path becomes an address; anything already absolute is left alone. */
     private address;
     private client;

package/dist/connection/HttpTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HttpTransport.d.ts","sourceRoot":"","sources":["../../src/connection/HttpTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAG5C,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,oBAAoB,CAAC;AAS5B,qBAAa,aAAc,YAAW,aAAa;IA6B/C,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IACzC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO;IApC1B;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAU;IAE/B,OAAO,CAAC,QAAQ,CAA8B;IAE9C;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA6B;IACjD,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,KAAK,CAAuB;gBAGjB,YAAY,GAAE,MAAM,YAAyB,EAC3C,MAAM,GAAE,OAAO,GAAG,IAAW;IAChD;;;;;OAKG;IACc,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO;IAGtE;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAgC/C,0EAA0E;IAC1E,OAAO,IAAI,MAAM,GAAG,IAAI;IAIxB;;;;;;OAMG;IACH,kBAAkB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAQzC;;;;;OAKG;IACH,kBAAkB,IAAI,OAAO;IAI7B;;;;;;;OAOG;IACH,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IASzC;;;;;;;OAOG;IACH,SAAS,CAAC,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAIlD;;;;;;;OAOG;IACG,SAAS,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmG7D,uEAAuE;IACvE,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI1C,4EAA4E;IAC5E,aAAa,IAAI,IAAI;IASrB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,KAAK;IAcb,0EAA0E;IAC1E,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,MAAM;IAuBd;;;;;;OAMG;IACG,IAAI,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAEvD;;;;;;OAMG;IACG,KAAK,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAExD;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIzE;;;;;;;;;;;;;OAaG;cACa,YAAY,CAC1B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;YAInB,QAAQ;CA4BvB"}
+{"version":3,"file":"HttpTransport.d.ts","sourceRoot":"","sources":["../../src/connection/HttpTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAG5C,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,oBAAoB,CAAC;AAwC5B;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAaxE;AASD,qBAAa,aAAc,YAAW,aAAa;IA6B/C,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IACzC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO;IApC1B;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAU;IAE/B,OAAO,CAAC,QAAQ,CAA8B;IAE9C;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA6B;IACjD,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,KAAK,CAAuB;gBAGjB,YAAY,GAAE,MAAM,YAAyB,EAC3C,MAAM,GAAE,OAAO,GAAG,IAAW;IAChD;;;;;OAKG;IACc,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO;IAGtE;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAgC/C,0EAA0E;IAC1E,OAAO,IAAI,MAAM,GAAG,IAAI;IAIxB;;;;;;OAMG;IACH,kBAAkB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAQzC;;;;;OAKG;IACH,kBAAkB,IAAI,OAAO;IAI7B;;;;;;;OAOG;IACH,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IASzC;;;;;;;OAOG;IACH,SAAS,CAAC,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAIlD;;;;;;;OAOG;IACG,SAAS,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmG7D,uEAAuE;IACvE,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI1C,4EAA4E;IAC5E,aAAa,IAAI,IAAI;IASrB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,KAAK;IA6Bb;;;;;OAKG;IACH,SAAS,CAAC,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAItD,0EAA0E;IAC1E,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,MAAM;IAuBd;;;;;;OAMG;IACG,IAAI,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAEvD;;;;;;OAMG;IACG,KAAK,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAExD;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIzE;;;;;;;;;;;;;OAaG;cACa,YAAY,CAC1B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;YAInB,QAAQ;CA4BvB"}

package/dist/connection/HttpTransport.js

@@ -24,10 +24,69 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpTransport = void 0;
+exports.isStatefulRequest = isStatefulRequest;
 const node_https_1 = require("node:https");
 const axios_1 = __importDefault(require("axios"));
 const cookies_js_1 = require("../utils/cookies.js");
 const csrfConfig_js_1 = require("./csrfConfig.js");
+/** The cookie that names a stateful ABAP context. */
+const CONTEXT_COOKIE = 'sap-contextid';
+/**
+ * A `Cookie` header without `sap-contextid`, for a request that is not stateful.
+ *
+ * `sap-contextid` names the stateful ABAP context a `LOCK` opened, and SAP
+ * routes any request carrying it into that context — header or no header. So
+ * a "stateless" request that carried it was not stateless: it ran in the
+ * lock's context. Measured on E19 (BASIS 816) and E98 (BASIS 756), 2026-09-27,
+ * one connection, a package locked, written and unlocked twice:
+ *
+ * - E19: the second `PUT` answered 400 PAK/058 "Package … is already locked" —
+ *   the first write's save was still in that context's `CL_PACKAGE` buffer;
+ * - E98: every `PUT` answered 423 "Resource … is not locked (invalid lock
+ *   handle)".
+ *
+ * Without the cookie on the non-stateful requests, both systems wrote twice
+ * and deleted on the same connection. Eclipse ADT does the same thing its
+ * own way: its trace shows one stateful session for `LOCK` and `UNLOCK`
+ * alone, and every other request — the `PUT` included — in a session of its
+ * own.
+ *
+ * The jar itself keeps the cookie: the stateful requests that follow, the
+ * `UNLOCK` above all, still need to reach the context that holds the lock.
+ */
+function withoutContextCookie(cookie) {
+    if (!cookie)
+        return cookie;
+    const kept = cookie
+        .split(/;\s*/)
+        .filter((pair) => pair && pair.split('=')[0]?.trim() !== CONTEXT_COOKIE)
+        .join('; ');
+    return kept || undefined;
+}
+/** The header that asks SAP for the stateful session over HTTP. */
+const SESSION_TYPE_HEADER = 'x-sap-adt-sessiontype';
+/**
+ * Whether the request runs in the stateful session: marked so by the
+ * connection, or — kept for callers that still write it themselves — carrying
+ * the session header already.
+ *
+ * Exported for the wires that rewrite a request before sending it: the
+ * verdict has to be taken on the request as the caller made it.
+ */
+function isStatefulRequest(request) {
+    if (request.stateful)
+        return true;
+    const headers = request.headers;
+    if (!headers)
+        return false;
+    for (const [name, value] of Object.entries(headers)) {
+        if (name.toLowerCase() === SESSION_TYPE_HEADER &&
+            String(value).toLowerCase() === 'stateful') {
+            return true;
+        }
+    }
+    return false;
+}
 /** A 404 there means the system has no such endpoint, not that it is unwell. */
 function absentEndpoint(error) {
     const status = error
@@ -307,17 +366,46 @@ class HttpTransport {
      * cookie, and replacing it would send the request out unauthenticated while
      * looking like it carried a session.
      */
-    dress(headers) {
+    dress(request) {
+        const headers = request.headers;
+        const stateful = isStatefulRequest(request);
         const dressed = {
             ...this.affinityHeaders(),
             ...this.sessionHeaders(),
+            ...(stateful ? this.sessionTypeHeaders() : {}),
             ...headers,
         };
-        const merged = (0, cookies_js_1.mergeCookieHeaders)(headers?.Cookie, this.combined ?? undefined);
-        if (merged)
-            dressed.Cookie = merged;
+        // Whatever the caller spelled the header as: HTTP does not tell `Cookie`
+        // from `cookie`, and a lowercase one spread in above would bypass the
+        // filter below.
+        let callerCookie;
+        for (const name of Object.keys(dressed)) {
+            if (name.toLowerCase() !== 'cookie')
+                continue;
+            callerCookie = (0, cookies_js_1.mergeCookieHeaders)(callerCookie, dressed[name]);
+            delete dressed[name];
+        }
+        const merged = (0, cookies_js_1.mergeCookieHeaders)(callerCookie, this.combined ?? undefined);
+        // Filtered on the merged header, not only on the jar: a caller's own
+        // `Cookie` can carry the context too — the connection's CSRF and 401
+        // retries put the whole jar there — and a non-stateful request must not
+        // reach the context whichever way the cookie arrived.
+        const cookie = stateful ? merged : withoutContextCookie(merged);
+        if (cookie)
+            dressed.Cookie = cookie;
+        else
+            delete dressed.Cookie;
         return dressed;
     }
+    /**
+     * How this wire asks for the stateful session: `x-sap-adt-sessiontype:
+     * stateful`, as Eclipse sends on its `LOCK` and `UNLOCK` over HTTP. A wire
+     * whose system is hurt by the header overrides this (BASIS 7.40, see
+     * `LegacyOnPremHttpTransport`).
+     */
+    sessionTypeHeaders() {
+        return { [SESSION_TYPE_HEADER]: 'stateful' };
+    }
     /** A path becomes an address; anything already absolute is left alone. */
     address(url) {
         if (!url.startsWith('/') || !this.options.baseUrl)
@@ -367,7 +455,7 @@ class HttpTransport {
      * to add it.
      */
     async send(request) {
-        return this.dispatch(request, this.dress(request.headers));
+        return this.dispatch(request, this.dress(request));
     }
     /**
      * Send EXACTLY these headers, with nothing of the wire's live state mixed in.

package/dist/connection/IAdtTransport.d.ts

@@ -37,6 +37,18 @@ export interface IAdtTransportRequest {
      * this seam is written against.
      */
     validateStatus?: (status: number) => boolean;
+    /**
+     * Whether the request runs in the stateful session — the one a lock is
+     * taken and released in.
+     *
+     * A flag rather than a header, because how a session is asked for is the
+     * wire's own business. Over HTTP it is `x-sap-adt-sessiontype: stateful`
+     * plus the `sap-contextid` cookie that addresses the context; over RFC it is
+     * neither — Eclipse's JCo trace carries no session header at all. A request
+     * that is not stateful must not reach that context: see
+     * `HttpTransport.dress`.
+     */
+    stateful?: boolean;
 }
 /** What came back, in the terms every transport can produce. */
 export interface IAdtTransportResponse {

package/dist/connection/IAdtTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IAdtTransport.d.ts","sourceRoot":"","sources":["../../src/connection/IAdtTransport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"IAdtTransport.d.ts","sourceRoot":"","sources":["../../src/connection/IAdtTransport.ts"],"names":[],"mappings":"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"}

package/dist/connection/LegacyOnPremHttpTransport.d.ts

@@ -16,8 +16,11 @@ import type { IAdtTransportRequest, IAdtTransportResponse } from './IAdtTranspor
 import { OnPremHttpTransport } from './OnPremHttpTransport.js';
 export declare class LegacyOnPremHttpTransport extends OnPremHttpTransport {
     readonly kind = "onprem-http-legacy";
+    /** The stateful header is the one this system is hurt by, so it asks with none. */
+    protected sessionTypeHeaders(): Record<string, string>;
     /**
-     * The header never goes out, whatever the caller set the session type to.
+     * The header never goes out, whatever the caller set the session type to —
+     * not even when a caller wrote it into the request themselves.
      *
      * Dropped here rather than refused above: `setSessionType()` records what the
      * caller wants, and what actually travels is the wire's business. A caller

package/dist/connection/LegacyOnPremHttpTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LegacyOnPremHttpTransport.d.ts","sourceRoot":"","sources":["../../src/connection/LegacyOnPremHttpTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAI/D,qBAAa,yBAA0B,SAAQ,mBAAmB;IAChE,SAAkB,IAAI,wBAAwB;IAE9C;;;;;;;;OAQG;IACY,IAAI,CACjB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAIjC,OAAO,CAAC,kBAAkB;IAY1B;;;;;;;OAOG;IACM,kBAAkB,IAAI,OAAO;CAGvC"}
+{"version":3,"file":"LegacyOnPremHttpTransport.d.ts","sourceRoot":"","sources":["../../src/connection/LegacyOnPremHttpTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAI/D,qBAAa,yBAA0B,SAAQ,mBAAmB;IAChE,SAAkB,IAAI,wBAAwB;IAE9C,mFAAmF;cAChE,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAI/D;;;;;;;;;OASG;IACY,IAAI,CACjB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAUjC,OAAO,CAAC,kBAAkB;IAY1B;;;;;;;OAOG;IACM,kBAAkB,IAAI,OAAO;CAGvC"}

package/dist/connection/LegacyOnPremHttpTransport.js

@@ -15,12 +15,18 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LegacyOnPremHttpTransport = void 0;
+const HttpTransport_js_1 = require("./HttpTransport.js");
 const OnPremHttpTransport_js_1 = require("./OnPremHttpTransport.js");
 const SESSION_TYPE_HEADER = 'x-sap-adt-sessiontype';
 class LegacyOnPremHttpTransport extends OnPremHttpTransport_js_1.OnPremHttpTransport {
     kind = 'onprem-http-legacy';
+    /** The stateful header is the one this system is hurt by, so it asks with none. */
+    sessionTypeHeaders() {
+        return {};
+    }
     /**
-     * The header never goes out, whatever the caller set the session type to.
+     * The header never goes out, whatever the caller set the session type to —
+     * not even when a caller wrote it into the request themselves.
      *
      * Dropped here rather than refused above: `setSessionType()` records what the
      * caller wants, and what actually travels is the wire's business. A caller
@@ -29,7 +35,13 @@ class LegacyOnPremHttpTransport extends OnPremHttpTransport_js_1.OnPremHttpTrans
      * would move its locks somewhere they cannot be released.
      */
     async send(request) {
-        return super.send(this.withoutSessionType(request));
+        // Decided before the header is dropped: a caller that asked for the
+        // stateful session by writing the header itself still gets its context
+        // cookie, only without the header this system is hurt by.
+        return super.send({
+            ...this.withoutSessionType(request),
+            stateful: (0, HttpTransport_js_1.isStatefulRequest)(request),
+        });
     }
     withoutSessionType(request) {
         if (!request.headers)

package/dist/connection/RfcTransport.d.ts

@@ -11,9 +11,12 @@
  * "invalid lock handle" on legacy systems (BASIS < 7.50) where stateful HTTP
  * sessions are not usable.
  *
- * **What is NOT here.** Cookies, the CSRF token, `x-sap-adt-sessiontype` and
- * the session lifecycle belong to the connection above this seam and are
- * already in `request.headers` by the time `send()` is called. A transport that
+ * **What is NOT here.** Cookies, the CSRF token and the session lifecycle
+ * belong to the connection above this seam and are already in
+ * `request.headers` by the time `send()` is called. `x-sap-adt-sessiontype` is
+ * not sent at all: `request.stateful` is HTTP's to express, and over RFC
+ * Eclipse's JCo trace carries no session header — its stateful session is a
+ * connection of its own, not a header on the request. A transport that
  * also captured cookies would be doing that work twice, and the two copies
  * would disagree the first time one of them was cleared.
  */

package/dist/connection/RfcTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RfcTransport.d.ts","sourceRoot":"","sources":["../../src/connection/RfcTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EACV,oBAAoB,EAEpB,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,oBAAoB,CAAC;AAE5B,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,CACF,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAgFD,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAKD,qBAAa,YAAa,YAAW,gBAAgB;IA+EjD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhF1B,QAAQ,CAAC,IAAI,SAAS;IAEtB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAG,QAAQ,CAAU;IAEpC,OAAO,CAAC,YAAY,CAAiC;IACrD,kEAAkE;IAClE,OAAO,CAAC,cAAc,CAAM;IAE5B;;;;;;OAMG;IACH,MAAM,IAAI,IAAI;IAEd,2CAA2C;IAC3C,OAAO,IAAI,IAAI;IAIf;;;;;OAKG;IACG,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAE9D,+BAA+B;IAC/B,SAAS,IAAI,IAAI;IAIjB;;;OAGG;IACH,cAAc,IAAI,IAAI;IAEtB;;;OAGG;IACH,6EAA6E;IAC7E,kBAAkB,IAAI,OAAO;IAI7B,kBAAkB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAQzC,2EAA2E;IAC3E,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAIzC;;;;OAIG;IACH,aAAa,IAAI,IAAI;IAErB;;;;;OAKG;gBAEgB,OAAO,EAAE,MAAM,gBAAgB,EAC/B,MAAM,GAAE,OAAO,GAAG,IAAW,EAC7B,OAAO,GAAE,oBAAyB;IAGrD,oDAAoD;IACpD,OAAO,CAAC,OAAO;IAcT,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB3B,0DAA0D;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAatB,IAAI,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAkK1E"}
+{"version":3,"file":"RfcTransport.d.ts","sourceRoot":"","sources":["../../src/connection/RfcTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EACV,oBAAoB,EAEpB,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,oBAAoB,CAAC;AAE5B,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,CACF,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAgFD,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAKD,qBAAa,YAAa,YAAW,gBAAgB;IA+EjD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhF1B,QAAQ,CAAC,IAAI,SAAS;IAEtB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAG,QAAQ,CAAU;IAEpC,OAAO,CAAC,YAAY,CAAiC;IACrD,kEAAkE;IAClE,OAAO,CAAC,cAAc,CAAM;IAE5B;;;;;;OAMG;IACH,MAAM,IAAI,IAAI;IAEd,2CAA2C;IAC3C,OAAO,IAAI,IAAI;IAIf;;;;;OAKG;IACG,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAE9D,+BAA+B;IAC/B,SAAS,IAAI,IAAI;IAIjB;;;OAGG;IACH,cAAc,IAAI,IAAI;IAEtB;;;OAGG;IACH,6EAA6E;IAC7E,kBAAkB,IAAI,OAAO;IAI7B,kBAAkB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAQzC,2EAA2E;IAC3E,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAIzC;;;;OAIG;IACH,aAAa,IAAI,IAAI;IAErB;;;;;OAKG;gBAEgB,OAAO,EAAE,MAAM,gBAAgB,EAC/B,MAAM,GAAE,OAAO,GAAG,IAAW,EAC7B,OAAO,GAAE,oBAAyB;IAGrD,oDAAoD;IACpD,OAAO,CAAC,OAAO;IAcT,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB3B,0DAA0D;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAatB,IAAI,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAkK1E"}

package/dist/connection/RfcTransport.js

@@ -12,9 +12,12 @@
  * "invalid lock handle" on legacy systems (BASIS < 7.50) where stateful HTTP
  * sessions are not usable.
  *
- * **What is NOT here.** Cookies, the CSRF token, `x-sap-adt-sessiontype` and
- * the session lifecycle belong to the connection above this seam and are
- * already in `request.headers` by the time `send()` is called. A transport that
+ * **What is NOT here.** Cookies, the CSRF token and the session lifecycle
+ * belong to the connection above this seam and are already in
+ * `request.headers` by the time `send()` is called. `x-sap-adt-sessiontype` is
+ * not sent at all: `request.stateful` is HTTP's to express, and over RFC
+ * Eclipse's JCo trace carries no session header — its stateful session is a
+ * connection of its own, not a header on the request. A transport that
  * also captured cookies would be doing that work twice, and the two copies
  * would disagree the first time one of them was cleared.
  */

package/docs/INDEX.md

@@ -69,7 +69,7 @@ mcp-abap-connection/
 
 ### Session Management
 - **Overview**: [USAGE.md - Session Management](./USAGE.md#session-management)
-- **Stateful Mode**: Use `setSessionType('stateful')` for session headers
+- **Stateful Mode**: Use `setSessionType('stateful')` for the LOCK / UNLOCK context; use stateless mode for GET / PUT
 - **Session State Persistence**: Handled by `@mcp-abap-adt/auth-broker` package
 - **API Methods**:
   - `getSessionId()` - Get current session ID (auto-generated UUID)

package/docs/STATEFUL_SESSION_GUIDE.md

@@ -1,8 +1,8 @@
 # Stateful Session Guide (Connection Layer)
 
 > **The header is not what tracks your lock.** `setSessionType('stateful')` sets
-> a per-request header and nothing more — another handler can flip it back while
-> your lock is genuinely open, and a batch never sets it at all. Nothing in this
+> the mode for subsequent requests; HTTP uses it to select the session header
+> and context cookie. Another handler can flip it back while your lock is open. Nothing in this
 > layer tracks locks: that belongs to `@mcp-abap-adt/adt-clients`, which holds the
 > handles and pairs each LOCK with its UNLOCK per object. What the connection
 > offers is `beginCriticalSection()` / `endCriticalSection()`, so a short timeout
@@ -24,6 +24,39 @@ The connection layer **does not** decide when to lock/unlock objects—that logi
 
 ---
 
+## HTTP context isolation (9.3.1)
+
+The authentication session (`SAP_SESSIONID`) and the stateful ABAP context
+(`sap-contextid`) have different roles. HTTP requests keep authentication
+cookies and the CSRF token in either mode. Only stateful requests carry
+`sap-contextid`; the jar retains it while stateless requests run so that a
+later UNLOCK can still reach the context holding the lock.
+
+Use stateful mode for LOCK and UNLOCK, and stateless mode for the intervening
+GET and PUT. Passing a lock handle to PUT does not require the context cookie.
+The ADT clients choose these modes; callers using connectors directly must
+choose the mode for each operation themselves.
+
+Before 9.3.1, the whole jar went out even in stateless mode. After LOCK, a PUT
+therefore ran in the lock's context. Package updates on E19 (BASIS 816) failed
+on the second write with **400 PAK/058, “Package … is already locked”**, and a
+subsequent delete failed too. On E98 (BASIS 756), PUT failed with **423,
+“Resource … is not locked (invalid lock handle)”**. Filtering the context
+cookie allowed two updates and a delete on one connection on both systems.
+The filter also applies to cookies supplied in request headers and retries.
+
+| Transport | Stateful request |
+| --- | --- |
+| HTTP (on-prem / cloud) | Sends `x-sap-adt-sessiontype: stateful` and the context cookie, when held |
+| Legacy on-prem HTTP | Keeps the context cookie but omits the session-type header |
+| RFC | Uses its RFC conversation; `setSessionType()` adds no HTTP session-type header |
+
+A caller-supplied stateful header is also recognized, including by the legacy
+HTTP transport before it removes that header. Custom `IAdtTransport`
+implementations must read `request.stateful`; the connection no longer adds
+`x-sap-adt-sessiontype` itself. The cookie fix was verified on E19 and E98;
+BASIS 7.40 and ABAP Cloud were not integration-tested for this change.
+
 ## Enabling Stateful Sessions
 
 Every example below builds on this much, so it is stated once:
@@ -62,10 +95,10 @@ const connection = new AdtOnPremConnector(
 );
 await connection.connect();   // required before any request
 
-// Enable stateful session mode (adds x-sap-adt-sessiontype: stateful header)
+// Enable the stateful HTTP context (session header and context cookie)
 connection.setSessionType('stateful');
 
-// Now all requests share the same session (cookies, CSRF token)
+// Following requests use the stateful context until the mode is changed
 await connection.makeAdtRequest({ method: 'GET', url: '/sap/bc/adt/discovery' , timeout: getTimeout('default') });
 
 // Switch back to stateless
@@ -178,7 +211,7 @@ wrong fixes:
 |---|---|---|
 | **the connection** | one TCP socket | you, the network, a timeout firing. **Ends nothing on the server** |
 | **the HTTP session** | the ICF conversation, held by the cookie jar on this side | dropping the cookies, or a logoff. Nothing about it is in doubt |
-| **the ABAP session** | the server-side context named by `SAP_SESSIONID_<SID>_<CLIENT>` — the roll area a stateful request runs in | **only the server.** Its own idle timeout, which this side can neither read nor influence, or an explicit logoff |
+| **the ABAP session** | the authentication session named by `SAP_SESSIONID_<SID>_<CLIENT>`; `sap-contextid` separately addresses the stateful ABAP context | **only the server.** Its own idle timeout, which this side can neither read nor influence, or an explicit logoff |
 | **the lock** | an enqueue entry, **owned by the ABAP session** | that ABAP session ending. **When it goes, its locks go with it** |
 
 The two middle rows are the ones worth keeping apart, because everything that

package/docs/USAGE.md

@@ -250,9 +250,13 @@ await connection.connect();
 await connection.makeAdtRequest({ method: 'GET', url: '/sap/bc/adt/discovery' , timeout: getTimeout('default') });
 ```
 
-### Stateful Mode (Session Headers)
+### Stateful Mode (HTTP Context)
 
-Enable stateful session mode for operations requiring consistent session state:
+Use stateful mode for LOCK and UNLOCK, then stateless mode for GET and PUT
+between them. Since 9.3.1, stateless HTTP requests omit `sap-contextid` while
+retaining authentication cookies and the CSRF token. This prevents package
+writes from running in the lock context and failing with PAK/058 or an invalid
+lock handle. See [HTTP context isolation](./STATEFUL_SESSION_GUIDE.md#http-context-isolation-931).
 
 ```typescript
 import { AdtOnPremConnector, BasicAuthProvider, OnPremHttpTransport, getTimeout } from '@mcp-abap-adt/connection';
@@ -267,10 +271,10 @@ const connection = new AdtOnPremConnector(
 );
 await connection.connect();
 
-// Enable stateful session mode (adds x-sap-adt-sessiontype: stateful header)
+// Enable the stateful HTTP context (session header and context cookie)
 connection.setSessionType('stateful');
 
-// Now all requests share the same session (cookies, CSRF token)
+// Following requests use the stateful context until the mode is changed
 await connection.makeAdtRequest({ method: 'GET', url: '/sap/bc/adt/discovery' , timeout: getTimeout('default') });
 
 // Check session mode
@@ -972,7 +976,7 @@ See [examples/](../examples/) for complete working examples:
 ## Best Practices
 
 1. **State the three axes**: the connector says which system, the provider says which credential, the transport says which wire. Nothing is detected, and a connection that had to guess would guess wrong on the case that matters
-2. **Enable Stateful Mode**: Use `setSessionType('stateful')` for multi-request operations (locks, transactions)
+2. **Enable Stateful Mode**: Use `setSessionType('stateful')` for LOCK / UNLOCK and stateless mode for intervening GET / PUT
 3. **Token Refresh**: For cloud systems, use `@mcp-abap-adt/auth-broker` for token refresh functionality
 4. **Session State Persistence**: Use `@mcp-abap-adt/auth-broker` for session state persistence
 5. **Handle Errors Gracefully**: Wrap requests in try-catch blocks and check `failure.response` for HTTP errors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/connection",
-  "version": "9.3.0",
+  "version": "9.3.1",
   "description": "ABAP connection layer for MCP ABAP ADT server",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",