@ffschrattenecker/tm1-mcp-server 7.0.2 → 8.0.0

package/dist/lib/callgraph/tm1-adapter.js

@@ -17,14 +17,26 @@ import { rethrowIfSystemic } from "../../tm1-client/services/fallback.js";
 // Deliberately an allowlist of known-inert paths, not a denylist of
 // code-relevant ones: anything unrecognised keeps invalidating, so a new
 // mutating endpoint is stale-safe by default.
-const INERT_PATHS = [/\/ExecuteMDX/i, /\/Cellsets/i, /tm1\.Update/i];
+//
+// The read-only POST actions are listed too: executing a view, checking rules
+// or feeders, tracing, compiling. Running a PROCESS or CHORE is not — TI can
+// rewrite rules (RuleLoadFromFile) — so tm1.Execute is inert only on Views.
+const INERT_PATHS = [
+    /\/ExecuteMDX/i,
+    /\/Cellsets/i,
+    /tm1\.Update/i,
+    /\/Views\([^/]*\)\/tm1\.Execute\b/i,
+    /tm1\.(?:CheckRules|CheckFeeders|TraceFeeders|TraceCellCalculation|Compile)\b/i,
+    /\/CompileProcess\b/i,
+];
 function affectsReferenceGraph(path) {
     return !INERT_PATHS.some((re) => re.test(path));
 }
 const invalidateOnMutation = (e) => {
     if (!affectsReferenceGraph(e.path))
         return;
-    invalidateCallgraphCache();
+    // Scoped: a write on one connection says nothing about another's code.
+    invalidateCallgraphCache(e.connectionId);
 };
 /**
  * Wire the callgraph reference-index cache to tm1Events "mutation" notifications:
@@ -53,11 +65,31 @@ const inflight = new Map();
 // read that started before the mutation, so that result is merely old, not
 // wrong. What must not happen is that snapshot becoming the answer for everyone
 // else for the next 60 seconds.
-let generation = 0;
-export function invalidateCallgraphCache() {
-    const n = cache.size;
-    cache.clear();
-    generation++;
+//
+// Kept per connection (plus a global one for clear-all), so invalidating one
+// connection does not discard a build in flight for another.
+let globalGeneration = 0;
+const generations = new Map();
+const generationOf = (connectionId) => `${globalGeneration}:${generations.get(connectionId) ?? 0}`;
+/**
+ * Drop cached indexes for one connection, or for all of them when
+ * `connectionId` is omitted (the explicit tm1_invalidate_callgraph_cache tool).
+ */
+export function invalidateCallgraphCache(connectionId) {
+    if (connectionId === undefined) {
+        const n = cache.size;
+        cache.clear();
+        globalGeneration++;
+        return { cleared: n };
+    }
+    let n = 0;
+    for (const key of [...cache.keys()]) {
+        if (key.startsWith(`${connectionId}|`)) {
+            cache.delete(key);
+            n++;
+        }
+    }
+    generations.set(connectionId, (generations.get(connectionId) ?? 0) + 1);
     return { cleared: n };
 }
 export function getCallgraphCacheStats() {
@@ -89,10 +121,10 @@ export async function buildIndexFromTM1(tm1Client, opts = {}) {
     }
     const promise = (async () => {
         const start = Date.now();
-        const startGeneration = generation;
+        const startGeneration = generationOf(tm1Client.connectionId);
         const idx = await buildIndexInternal(tm1Client, includeControl);
         // Only publish if no invalidation happened while we were building.
-        if (generation === startGeneration) {
+        if (generationOf(tm1Client.connectionId) === startGeneration) {
             cache.set(key, {
                 index: idx,
                 ts: Date.now(),

package/dist/lib/callgraph/variableEnv.js

@@ -10,9 +10,10 @@
  * Multi-assignment (a variable is assigned different values) → dynamic,
  * because the value is no longer unambiguous at any given call site.
  */
+import { TI_VAR } from "../ti-identifier.js";
 const STRING_LITERAL_RE = /^'([^']*)'$/;
 const NUMERIC_LITERAL_RE = /^-?\d+(?:\.\d+)?$/;
-const IDENTIFIER_RE = /^[A-Za-z_]\w*$/;
+const IDENTIFIER_RE = new RegExp(`^${TI_VAR}$`);
 function neutralizeLine(line) {
     return line
         .replace(/'[^']*'/g, (s) => " ".repeat(s.length))
@@ -136,7 +137,7 @@ export function buildProcessEnv(text, paramNames, stopAtLineOrOptions) {
     };
     const assignedOnce = new Map();
     const seen = new Set();
-    const assignRe = /^\s*([A-Za-z_]\w*)\s*=\s*(.+?)\s*;?\s*(?:#.*)?$/;
+    const assignRe = new RegExp(`^\\s*(${TI_VAR})\\s*=\\s*(.+?)\\s*;?\\s*(?:#.*)?$`);
     const lines = text.split("\n");
     const limit = opts.stopAtLine !== undefined
         ? Math.min(opts.stopAtLine, lines.length)

package/dist/lib/cell-address.d.ts

@@ -18,5 +18,5 @@ export interface ResolvedAddress {
     /** Set when `Sandboxes` was left out and bound to `Base`. */
     sandboxDefaulted?: typeof BASE_SANDBOX;
 }
-export declare function resolveCellAddress(cubeName: string, cubeDimensions: readonly string[], given: readonly string[]): ResolvedAddress;
+export declare function resolveCellAddress(cubeName: string, cubeDimensions: readonly string[], given: readonly string[], outcome?: string): ResolvedAddress;
 //# sourceMappingURL=cell-address.d.ts.map

package/dist/lib/cell-address.js

@@ -39,7 +39,7 @@ export function bindLeftOutSandbox(cubeDimensions, elements) {
         return undefined;
     return [...elements.slice(0, pos), BASE_SANDBOX, ...elements.slice(pos)];
 }
-export function resolveCellAddress(cubeName, cubeDimensions, given) {
+export function resolveCellAddress(cubeName, cubeDimensions, given, outcome = "Nothing was written.") {
     const byLower = new Map(cubeDimensions.map((d, i) => [d.toLowerCase(), i]));
     const positions = [];
     const unknown = [];
@@ -68,7 +68,7 @@ export function resolveCellAddress(cubeName, cubeDimensions, given) {
     if (problems.length > 0) {
         throw new TM1Error({
             code: TM1ErrorCode.VALIDATION_ERROR,
-            message: `Dimensions do not match cube '${cubeName}' — ${problems.join("; ")}. Nothing was written.`,
+            message: `Dimensions do not match cube '${cubeName}' — ${problems.join("; ")}. ${outcome}`,
             hint: `Name every dimension of the cube (any order): ${cubeDimensions.join(", ")}. A dimension left out is not ignored — TM1 writes into its default member.${sandboxPos >= 0 ? ` Only ${SANDBOX_DIMENSION} may be left out; it is then bound to ${BASE_SANDBOX}.` : ""}`,
             details: JSON.stringify({ cubeDimensions, given }),
         });

package/dist/lib/complexity/antipatterns.js

@@ -7,6 +7,7 @@
  * to be reusable later from a single-process pre-commit lint entry point.
  */
 import { parseTiCode } from "../callgraph/tiParser.js";
+import { TI_VAR } from "../ti-identifier.js";
 const TABS = ["prolog", "metadata", "data", "epilog"];
 /**
  * Destructive ops that wipe data/objects. Unconditional use (no enclosing If)
@@ -84,7 +85,8 @@ function hasSideEffectRhs(expr) {
     }
     return false;
 }
-const IDENTIFIER_RE = /\b([A-Za-z_]\w*)\b/g;
+// Lookarounds instead of \b: \b does not fire after a trailing `.`/`$`/`%`.
+const IDENTIFIER_RE = new RegExp(`(?<![\\w.$%\`])(${TI_VAR})`, "g");
 const EXPAND_VAR_RE = /%([A-Za-z_]\w*)%/g;
 /** Extract all potential variable-read tokens from a raw TI expression/arg/condition string. */
 function collectReads(text, out) {

package/dist/lib/complexity/comment-classifier.js

@@ -16,13 +16,14 @@
  * directives). It is intentionally fuzzy — there is no parser that can tell a
  * disabled statement from prose with certainty.
  */
+import { TI_VAR } from "../ti-identifier.js";
 const CODE_SIGNALS = [
     // Statement terminator at end of line — the strongest TM1 signal.
     /;\s*$/,
     // Rule-area assignment: `['Sales'] = ...`
     /^\[[^\]]*\]\s*=/,
     // Variable / cube-cell assignment: `vX = ...` or `nResult=...` (not `==`).
-    /^[A-Za-z_]\w*\s*=(?!=)/,
+    new RegExp(`^${TI_VAR}\\s*=(?!=)`),
     // Known TM1 function call: `Name(` (case-insensitive — TM1 is).
     /\b(?:CellPutN|CellPutS|CellGetN|CellGetS|CellIsUpdateable|DB|DBRW|DBRA|DBSW|DBSS|AttrPutN|AttrPutS|AttrN|AttrS|ElementName|ElementIndex|DimensionElementInsert|DimensionElementComponentAdd|HierarchyElementInsert|ExecuteProcess|ExecuteCommand|RunProcess|ProcessQuit|ProcessBreak|ItemSkip|ItemReject|ViewZeroOut|CubeClearData|CubeSetLogChanges|ASCIIOutput|TextOutput|SubsetCreate|NumberToString|StringToNumber)\s*\(/i,
     // Control-flow keyword immediately followed by a paren: `IF(`, `WHILE (`.

package/dist/lib/feeders/element-type-cache.js

@@ -1,3 +1,4 @@
+import { tm1NameKey } from "../tm1-name.js";
 const VALID_TYPES = new Set(["Numeric", "Consolidated", "String"]);
 /**
  * Consecutive failed loads of one `(dim, hier)` slot before the cache stops
@@ -15,9 +16,6 @@ const VALID_TYPES = new Set(["Numeric", "Consolidated", "String"]);
  * clock buys nothing and would only drag `Date.now()` into the tests.
  */
 const MAX_CONSECUTIVE_LOAD_FAILURES = 3;
-function normalize(s) {
-    return s.toLowerCase();
-}
 export class ElementTypeCache {
     hierarchy;
     slots = new Map();
@@ -28,14 +26,14 @@ export class ElementTypeCache {
         this.hierarchy = hierarchy;
     }
     async getType(dim, hier, elem) {
-        const slotKey = `${normalize(dim)}|${normalize(hier)}`;
+        const slotKey = `${tm1NameKey(dim)}|${tm1NameKey(hier)}`;
         let slot = this.slots.get(slotKey);
         if (slot === undefined) {
             slot = await this.load(slotKey, dim, hier);
         }
         if (slot === null)
             return null;
-        return slot.get(normalize(elem)) ?? null;
+        return slot.get(tm1NameKey(elem)) ?? null;
     }
     async load(slotKey, dim, hier) {
         const inflight = this.pending.get(slotKey);
@@ -55,7 +53,7 @@ export class ElementTypeCache {
                 const m = new Map();
                 for (const e of elements) {
                     if (VALID_TYPES.has(e.type)) {
-                        m.set(normalize(e.name), e.type);
+                        m.set(tm1NameKey(e.name), e.type);
                     }
                 }
                 this.slots.set(slotKey, m);

package/dist/lib/naming/odata-filter.js

@@ -21,10 +21,11 @@
 // emitted expression in TypeScript so the property can be tested directly;
 // tests/unit/naming-odata-filter.test.ts asserts it over every rule class,
 // and the live suite asserts that TM1 agrees.
+import { escapeOdataLiteral } from "../../tm1-client/services/odata-page.js";
 import { SERVER_RESERVED_CHARS } from "./rules.js";
 /** OData string literal: single quotes double. */
 function lit(value) {
-    return `'${value.replace(/'/g, "''")}'`;
+    return `'${escapeOdataLiteral(value)}'`;
 }
 /**
  * `$filter` expression selecting elements that may violate a naming rule.

package/dist/lib/pro-parser.js

@@ -70,6 +70,9 @@ function parseSections(lines) {
         "574": [],
         "575": [],
     };
+    // Sections read by their line count keep trailing blank lines and spaces:
+    // TM1 stores and returns them, so trimming made every re-import differ.
+    const counted = new Set();
     let i = 0;
     while (i < lines.length) {
         const m = lines[i].match(SECTION_RE);
@@ -84,6 +87,7 @@ function parseSections(lines) {
             // TM1 writes an explicit line count ("572,138"). Trust it, so code lines
             // that look like a header (e.g. a literal "930,0") stay in the section.
             const count = parseInt(rawCount, 10);
+            counted.add(code);
             for (let taken = 0; taken < count && i < lines.length; taken++, i++) {
                 map[code].push(lines[i]);
             }
@@ -96,11 +100,16 @@ function parseSections(lines) {
             i++;
         }
     }
+    // A countless section runs to the next header, so its tail is ambiguous.
+    const text = (code) => {
+        const joined = map[code].join("\n");
+        return counted.has(code) ? joined : joined.trimEnd();
+    };
     return {
-        prolog: map["572"].join("\n").trimEnd(),
-        metadata: map["573"].join("\n").trimEnd(),
-        data: map["574"].join("\n").trimEnd(),
-        epilog: map["575"].join("\n").trimEnd(),
+        prolog: text("572"),
+        metadata: text("573"),
+        data: text("574"),
+        epilog: text("575"),
     };
 }
 function parseParameters(blocks) {

package/dist/lib/safe-regex.d.ts

@@ -1,15 +1,2 @@
-/**
- * Compile a user-supplied regex behind a ReDoS guard.
- *
- * Every `new RegExp(<user/LLM input>)` site must route through this helper:
- * `safe-regex` rejects catastrophic-backtracking patterns (e.g. `(a+)+$`) before
- * the pattern is ever constructed, so a malicious caller cannot freeze the Node
- * event loop and DoS the server. Invalid patterns are normalized to a
- * VALIDATION_ERROR instead of surfacing as a raw SyntaxError.
- *
- * @param pattern user-supplied regex source
- * @param flags   optional RegExp flags (e.g. "i", "gi")
- * @param label   human label for error messages (e.g. "nameRegex"); defaults to "regex"
- */
 export declare function compileUserRegex(pattern: string, flags?: string, label?: string): RegExp;
 //# sourceMappingURL=safe-regex.d.ts.map

package/dist/lib/safe-regex.js

@@ -1,25 +1,52 @@
 import safeRegex from "safe-regex";
+import regexpTree from "regexp-tree";
 import { TM1Error, TM1ErrorCode } from "../types.js";
 /**
- * Compile a user-supplied regex behind a ReDoS guard.
- *
- * Every `new RegExp(<user/LLM input>)` site must route through this helper:
- * `safe-regex` rejects catastrophic-backtracking patterns (e.g. `(a+)+$`) before
- * the pattern is ever constructed, so a malicious caller cannot freeze the Node
- * event loop and DoS the server. Invalid patterns are normalized to a
- * VALIDATION_ERROR instead of surfacing as a raw SyntaxError.
- *
- * @param pattern user-supplied regex source
- * @param flags   optional RegExp flags (e.g. "i", "gi")
- * @param label   human label for error messages (e.g. "nameRegex"); defaults to "regex"
+ * Unbounded repetition over a group that contains `|`, e.g. `(\w|\w)*` or
+ * `(a|ab)+`. safe-regex measures only star height, so it passes these, yet
+ * overlapping branches backtrack exponentially: `^(\w|\w)*!$` took 23.5 s on
+ * 30 characters and froze the event loop. Rejected as a class, since telling
+ * overlapping from disjoint branches is itself a hard problem; a character
+ * class (`[ab]+`) expresses the common intent without the risk.
  */
+function hasRepeatedAlternation(pattern) {
+    let ast;
+    try {
+        // Parsing a RegExp object avoids re-escaping `/`; compiling never runs it.
+        ast = regexpTree.parse(new RegExp(pattern));
+    }
+    catch {
+        return false; // new RegExp() below reports the syntax error
+    }
+    const containsDisjunction = (n) => {
+        if (!n || typeof n !== "object")
+            return false;
+        if (n.type === "Disjunction")
+            return true;
+        return Object.values(n).some(containsDisjunction);
+    };
+    const walk = (n) => {
+        if (!n || typeof n !== "object")
+            return false;
+        const node = n;
+        if (node.type === "Repetition" &&
+            node.quantifier &&
+            (node.quantifier.kind !== "Range" || node.quantifier.to === undefined) &&
+            node.quantifier.kind !== "?" &&
+            containsDisjunction(node.expression)) {
+            return true;
+        }
+        return Object.values(node).some(walk);
+    };
+    return walk(ast);
+}
 export function compileUserRegex(pattern, flags, label = "regex") {
-    if (!safeRegex(pattern)) {
+    if (!safeRegex(pattern) || hasRepeatedAlternation(pattern)) {
         throw new TM1Error({
             code: TM1ErrorCode.VALIDATION_ERROR,
             message: `${label} rejected: pattern risks catastrophic backtracking (ReDoS).`,
             details: pattern,
-            hint: "Avoid nested unbounded quantifiers like (a+)+ or (.*)* — simplify or anchor the pattern.",
+            hint: "Avoid nested unbounded quantifiers like (a+)+ or (.*)*, and repeating an alternation like (a|b)* — use a character class ([ab]*) or simplify the pattern.",
         });
     }
     try {

package/dist/lib/ti-identifier.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A TI variable name as TM1 accepts it. Besides letters, digits and `_`,
+ * the compiler takes `.`, `$`, `%` and backtick (measured on 11.8 and 12.5:
+ * `v.A = 1;`, `v$A`, `v%A` and `` v`A `` all compile), and ODBC columns
+ * carry such names into data-source variables. A plain `\w` identifier made
+ * the parser reject those lines, and every analysis then saw an empty tab.
+ *
+ * Function names stay `\w`-only; this is for variables.
+ */
+export declare const TI_VAR = "[A-Za-z_][\\w.$%`]*";
+//# sourceMappingURL=ti-identifier.d.ts.map

package/dist/lib/ti-identifier.js

@@ -0,0 +1,11 @@
+/**
+ * A TI variable name as TM1 accepts it. Besides letters, digits and `_`,
+ * the compiler takes `.`, `$`, `%` and backtick (measured on 11.8 and 12.5:
+ * `v.A = 1;`, `v$A`, `v%A` and `` v`A `` all compile), and ODBC columns
+ * carry such names into data-source variables. A plain `\w` identifier made
+ * the parser reject those lines, and every analysis then saw an empty tab.
+ *
+ * Function names stay `\w`-only; this is for variables.
+ */
+export const TI_VAR = "[A-Za-z_][\\w.$%`]*";
+//# sourceMappingURL=ti-identifier.js.map

package/dist/lib/tm1-name.d.ts

@@ -0,0 +1,9 @@
+/**
+ * TM1 name identity: the server treats `Total Year`, `totalyear` and
+ * `TOTAL YEAR` as the same object (case- and space-insensitive), so any
+ * client-side lookup against server names must key on this, not on
+ * `toLowerCase()` alone. Mirrors tm1py's `lower_and_drop_spaces`.
+ */
+export declare const tm1NameKey: (name: string) => string;
+export declare const tm1NameEquals: (a: string, b: string) => boolean;
+//# sourceMappingURL=tm1-name.d.ts.map

package/dist/lib/tm1-name.js

@@ -0,0 +1,9 @@
+/**
+ * TM1 name identity: the server treats `Total Year`, `totalyear` and
+ * `TOTAL YEAR` as the same object (case- and space-insensitive), so any
+ * client-side lookup against server names must key on this, not on
+ * `toLowerCase()` alone. Mirrors tm1py's `lower_and_drop_spaces`.
+ */
+export const tm1NameKey = (name) => name.toLowerCase().replace(/ /g, "");
+export const tm1NameEquals = (a, b) => tm1NameKey(a) === tm1NameKey(b);
+//# sourceMappingURL=tm1-name.js.map

package/dist/lib/v12-compat/deprecated-ti.js

@@ -230,8 +230,8 @@ export const V12_DEPRECATED_TI = new Map([
     {
         name: "SetOdbcUnicodeInterface",
         severity: "error",
-        issue: "ODBC data sources removed in v12 — external connector required",
-        suggestion: "Connect data via PA cloud connector / Files API",
+        issue: "SetODBCUnicodeInterface does not exist in v12 (compile fails); ODBCOpen/ODBCOutput/ODBCClose still compile",
+        suggestion: "Remove the call",
     },
     {
         name: "SwapAliasWithPrincipalName",

package/dist/session-manager.d.ts

@@ -8,6 +8,7 @@ export declare class SessionManager {
     private sessionCookie;
     private authInFlight;
     private keepAliveTimer;
+    private rejectedLogin;
     private readonly config;
     private readonly logger;
     private readonly profile;

package/dist/session-manager.js

@@ -2,6 +2,7 @@ import { createLogger } from "./logger.js";
 import { createConnectionProfile, } from "./tm1-client/connection/profile.js";
 import { getTm1Dispatcher, tm1Fetch } from "./tm1-client/dispatcher.js";
 import { PRODUCT, VERSION } from "./version.js";
+import { TM1Error, TM1ErrorCode } from "./types.js";
 const USER_AGENT = `${PRODUCT}/${VERSION}`;
 export class TimeoutError extends Error {
     timeoutMs;
@@ -31,6 +32,13 @@ export class SessionManager {
     sessionCookie = null;
     authInFlight = null;
     keepAliveTimer = null;
+    // Set once TM1 rejects the configured credentials (401/403 on login).
+    // Credentials come from env and cannot change without a restart, so every
+    // later attempt would be rejected the same way — and each one counts
+    // against MaximumLoginAttempts. Latching here keeps one failed login from
+    // becoming dozens (fan-out tools, the 401 retry, the keep-alive timer)
+    // and locking the account.
+    rejectedLogin = null;
     config;
     logger;
     profile;
@@ -61,6 +69,9 @@ export class SessionManager {
      * requests are using — the "staggered-401 re-auth churn" cascade.
      */
     async authenticate(staleCookie) {
+        if (this.rejectedLogin) {
+            throw this.rejectedLogin;
+        }
         if (staleCookie !== undefined &&
             this.sessionCookie !== null &&
             this.sessionCookie !== staleCookie) {
@@ -105,6 +116,19 @@ export class SessionManager {
         }));
         // Always consume body to release connection
         await response.text();
+        if (response.status === 401 || response.status === 403) {
+            this.rejectedLogin = new TM1Error({
+                code: TM1ErrorCode.AUTH_FAILED,
+                message: `Authentication failed with status ${response.status}: ${response.statusText}. ` +
+                    "No further login attempts are made, so the account is not locked out; " +
+                    "fix the credentials and restart the MCP server.",
+                httpStatus: response.status,
+                endpoint: loginReq.url,
+            });
+            this.logger.error({ endpoint: loginReq.url, status: response.status }, "Authentication rejected; login attempts stopped until restart");
+            this.stopKeepAlive();
+            throw this.rejectedLogin;
+        }
         if (!response.ok) {
             this.logger.error({ endpoint: loginReq.url, status: response.status }, "Authentication failed");
             throw new Error(`Authentication failed with status ${response.status}: ${response.statusText}`);

package/dist/tm1-client/connection/profile.js

@@ -1,6 +1,4 @@
-// OData single-quote escaping for a key segment (double the apostrophes),
-// then URL-encode. Mirrors the `enc` helper used across the service layer.
-const enc = (s) => encodeURIComponent(String(s).replace(/'/g, "''"));
+import { odataKey } from "../services/odata-page.js";
 function buildBasicToken(user, password) {
     return "Basic " + Buffer.from(`${user}:${password}`).toString("base64");
 }
@@ -79,7 +77,7 @@ function createV12Profile(config) {
     const database = config.database ?? "";
     // encodeURIComponent (not `enc`) for the instance: it's a bare path segment,
     // not an OData quoted key — no apostrophe-doubling needed, just percent-encoding.
-    const dbRoot = `/${encodeURIComponent(instance)}/api/v1/Databases('${enc(database)}')`;
+    const dbRoot = `/${encodeURIComponent(instance)}/api/v1/Databases('${odataKey(database)}')`;
     return {
         // Replacement FUNCTION, not a string: String.replace treats "$&"/"$$"/"$1"
         // in a string replacement specially, which would corrupt dbRoot if instance

package/dist/tm1-client/dispatcher.d.ts

@@ -1,5 +1,5 @@
 import { Agent } from "undici";
 import type { TM1Config } from "../config.js";
-export declare function getTm1Dispatcher(config: TM1Config): Agent | undefined;
+export declare function getTm1Dispatcher(config: TM1Config): Agent;
 export declare function tm1Fetch(url: string, init: RequestInit): Promise<Response>;
 //# sourceMappingURL=dispatcher.d.ts.map

package/dist/tm1-client/dispatcher.js

@@ -6,14 +6,26 @@
 //
 // The Agent is cached so connection-pooling stays effective across requests.
 import { Agent, fetch as undiciFetch } from "undici";
-let cachedAgent;
+//
+// headersTimeout/bodyTimeout are switched off on purpose. undici's defaults
+// (300 s each) end any request that has not answered after five minutes with
+// UND_ERR_HEADERS_TIMEOUT — measured: a 400 s budget died at 300.8 s on both
+// fetch paths. A TI process runs as long as it runs and TM1 has no timeout
+// for it, so the only limit is our own per-request AbortSignal (timeoutMs),
+// which http.ts maps to LOCK_TIMEOUT.
+const agents = new Map();
 export function getTm1Dispatcher(config) {
-    if (config.ssl.rejectUnauthorized)
-        return undefined;
-    if (!cachedAgent) {
-        cachedAgent = new Agent({ connect: { rejectUnauthorized: false } });
+    const verify = config.ssl.rejectUnauthorized;
+    let agent = agents.get(verify);
+    if (!agent) {
+        agent = new Agent({
+            connect: { rejectUnauthorized: verify },
+            headersTimeout: 0,
+            bodyTimeout: 0,
+        });
+        agents.set(verify, agent);
     }
-    return cachedAgent;
+    return agent;
 }
 // Node's BUILT-IN fetch silently drops Set-Cookie headers when handed a
 // dispatcher from the npm undici package (cross-instance Headers handling;

package/dist/tm1-client/http.d.ts

@@ -2,6 +2,7 @@ import type pino from "pino";
 import { type TM1Config } from "../config.js";
 import type { SessionManager } from "../session-manager.js";
 import { TM1Error } from "../types.js";
+import { type Tm1MutationEvent } from "../lib/tm1-events.js";
 export interface RequestOptions {
     timeoutMs?: number;
     signal?: AbortSignal;
@@ -13,6 +14,15 @@ export declare class TM1HttpClient {
     protected readonly sessionManager: SessionManager;
     private readonly profile;
     constructor(config: TM1Config, sessionManager: SessionManager, logger: pino.Logger);
+    private readonly mutationListeners;
+    /**
+     * @internal — subscribe to THIS connection's successful mutations. Unlike
+     * the process-global `tm1Events` bus, listeners die with the client, so a
+     * per-connection cache needs no unsubscribe and never sees another
+     * connection's writes.
+     */
+    onMutation(listener: (e: Tm1MutationEvent) => void): void;
+    private emitMutation;
     /**
      * TM1 major version (11 | 12) — the single numeric source of truth for
      * version-conditional service code. Branch on this, never on the display
@@ -45,6 +55,17 @@ export declare class TM1HttpClient {
      */
     /** @internal — for Service-layer use; not part of the public consumer API. */
     requestRaw(method: string, path: string, opts?: RequestOptions): Promise<string>;
+    /**
+     * Same request as requestRaw, but hands back the bytes instead of a string.
+     *
+     * requestRaw decodes the body as UTF-8, which silently destroys anything
+     * that is not text — a spreadsheet read that way comes back as replacement
+     * characters. Callers that may face binary content use this and decide how
+     * to present it.
+     */
+    /** @internal — for Service-layer use; not part of the public consumer API. */
+    requestRawBytes(method: string, path: string, opts?: RequestOptions): Promise<Buffer>;
+    private fetchRaw;
     /**
      * Make an authenticated HTTP request with a binary body (Buffer/Uint8Array).
      * Used for blob/file uploads where the body is raw bytes (not JSON).