sap-ai-dev-toolkit 0.9.9917 → 0.9.9920

package/src/integration-http.mjs

@@ -1,6 +1,5 @@
-// OAuth client-credentials HTTP client for one CPI or APIM tenant.
-// Requests are pinned to the configured tenant origin, bodies are size
-// capped, and token/error responses are never echoed raw.
+// Origin-pinned OAuth and private static-authorization HTTP clients.
+// Shared transport caps bodies, rejects redirects, and bounds complete reads.
 import { EnvHttpProxyAgent, fetch as undiciFetch } from 'undici';
 import { diagnosticText } from './redact.mjs';
 
@@ -13,11 +12,13 @@ const SERVER_RETRIES = 2;
 const RETRYABLE_STATUS = new Set([500, 502, 503, 504]);
 // Only idempotent methods are retried; POST (create/deploy/import) is never re-sent.
 const RETRYABLE_METHODS = new Set(['GET', 'PUT']);
+const PAGINATION_HEADERS = new Set(['elements-next-page-token', 'nextpage']);
 
 export class IntegrationError extends Error {
-  constructor(message) {
+  constructor(message, evidence = {}) {
     super(message);
     this.name = 'IntegrationError';
+    Object.assign(this, evidence);
   }
 }
 
@@ -33,22 +34,37 @@ export function odataDate(value) {
   return match ? new Date(Number(match[1])).toISOString() : value;
 }
 
-async function readCapped(response, limit, label) {
+function discard(response) {
+  // Cancellation is cleanup, not another unbounded wait on a remote stream.
+  void response.body?.cancel().catch(() => {});
+}
+
+async function readCapped(response, limit, label, signal) {
   const declared = Number(response.headers.get('content-length'));
   if (Number.isFinite(declared) && declared > limit) {
-    await response.body?.cancel().catch(() => {});
+    discard(response);
     throw new IntegrationError(`${label} response exceeded the safe size limit`);
   }
   if (!response.body) return new Uint8Array(0);
+  const reader = response.body.getReader();
+  const abort = () => { void reader.cancel().catch(() => {}); };
+  signal?.addEventListener('abort', abort, { once: true });
   const chunks = [];
   let total = 0;
-  for await (const chunk of response.body) {
-    total += chunk.byteLength;
-    if (total > limit) {
-      await response.body.cancel().catch(() => {});
-      throw new IntegrationError(`${label} response exceeded the safe size limit`);
+  try {
+    for (;;) {
+      const { done, value: chunk } = await reader.read();
+      if (done) break;
+      total += chunk.byteLength;
+      if (total > limit) throw new IntegrationError(`${label} response exceeded the safe size limit`);
+      chunks.push(chunk);
     }
-    chunks.push(chunk);
+  } catch (error) {
+    void reader.cancel().catch(() => {});
+    throw error;
+  } finally {
+    signal?.removeEventListener('abort', abort);
+    reader.releaseLock();
   }
   const bytes = new Uint8Array(total);
   let offset = 0;
@@ -73,11 +89,60 @@ function sapMessage(bodyText) {
   return bodyText.slice(0, 400);
 }
 
-function setCookiePairs(headers) {
-  const values = typeof headers.getSetCookie === 'function'
+function setCookieValues(headers) {
+  return typeof headers.getSetCookie === 'function'
     ? headers.getSetCookie()
-    : [headers.get('set-cookie')].filter(Boolean);
-  return values.map(value => value.split(';')[0].trim()).filter(Boolean);
+    : (headers.get('set-cookie') || '').split(/,(?=\s*[^;,=\s]+=)/).filter(Boolean);
+}
+
+function setCookiePairs(headers) {
+  return setCookieValues(headers).map(value => value.split(';')[0].trim()).filter(Boolean);
+}
+
+// This deliberately host-only jar never honors a server-supplied Domain. It is
+// private to one pinned client and only enabled for broker management sessions.
+function sessionCookies(now) {
+  const jar = new Map();
+  return {
+    remember(headers, target) {
+      for (const value of setCookieValues(headers)) {
+        if (value.length > 4096) continue;
+        const [pair, ...attributes] = value.split(';');
+        const separator = pair.indexOf('=');
+        if (separator <= 0) continue;
+        const name = pair.slice(0, separator).trim();
+        const content = pair.slice(separator + 1).trim();
+        if (!/^[!#$%&'*+\-.^_`|~\w]+$/.test(name) || /[\x00-\x20\x7f;,]/.test(content)) continue;
+        let path = target.pathname.slice(0, target.pathname.lastIndexOf('/')) || '/';
+        let secure = false;
+        let expires = Infinity;
+        let maxAge;
+        for (const attribute of attributes) {
+          const index = attribute.indexOf('=');
+          const key = (index < 0 ? attribute : attribute.slice(0, index)).trim().toLowerCase();
+          const setting = index < 0 ? '' : attribute.slice(index + 1).trim();
+          if (key === 'path' && setting.startsWith('/')) path = setting;
+          if (key === 'secure') secure = true;
+          if (key === 'max-age' && /^-?\d+$/.test(setting)) maxAge = Number(setting);
+          if (key === 'expires' && Number.isFinite(Date.parse(setting))) expires = Date.parse(setting);
+        }
+        if (maxAge !== undefined) expires = now() + maxAge * 1000;
+        const key = `${path}\0${name}`;
+        if (expires <= now()) jar.delete(key);
+        else if (jar.has(key) || jar.size < 100) jar.set(key, { name, content, path, secure, expires });
+      }
+    },
+    header(target) {
+      const matches = [];
+      for (const [key, cookie] of jar) {
+        if (cookie.expires <= now()) { jar.delete(key); continue; }
+        const inPath = target.pathname === cookie.path
+          || target.pathname.startsWith(cookie.path.endsWith('/') ? cookie.path : `${cookie.path}/`);
+        if (inPath && (!cookie.secure || target.protocol === 'https:')) matches.push(cookie);
+      }
+      return matches.sort((a, b) => b.path.length - a.path.length).map(cookie => `${cookie.name}=${cookie.content}`).join('; ');
+    }
+  };
 }
 
 // undici flags EnvHttpProxyAgent as experimental with a process warning that lands in the middle of the
@@ -97,7 +162,17 @@ function envProxyAgent(options) {
 }
 
 /** Create a tenant-scoped client using OAuth client credentials. */
-export function createServiceClient({
+export function createServiceClient(options) {
+  return createTransportClient({ ...options, oauth: true });
+}
+
+/** Static authorization stays in a host-private closure, never a request input. */
+export function createStaticServiceClient({ authorization, ...options }) {
+  if (typeof authorization !== 'function') throw new IntegrationError('Static authorization must be a private function');
+  return createTransportClient({ ...options, authorization, oauth: false, exposeErrorDetails: false });
+}
+
+function createTransportClient({
   label,
   url,
   tokenUrl,
@@ -107,9 +182,16 @@ export function createServiceClient({
   env = process.env,
   fetchImpl = undiciFetch,
   now = Date.now,
-  retryDelayMs = 500
+  retryDelayMs = 500,
+  exposeErrorDetails = true,
+  oauth,
+  authorization,
+  reuseCookies = false
 }) {
-  const origin = new URL(url).origin;
+  const base = new URL(url);
+  if (base.username || base.password || base.search || base.hash) throw new IntegrationError(`${label} base URL must not contain credentials, query, or fragment`);
+  const origin = base.origin;
+  const cookies = reuseCookies ? sessionCookies(now) : null;
   const httpProxy = env.HTTP_PROXY || env.http_proxy;
   const httpsProxy = env.HTTPS_PROXY || env.https_proxy;
   const dispatcher = httpProxy || httpsProxy
@@ -117,40 +199,92 @@ export function createServiceClient({
     : undefined;
   const transportOptions = dispatcher ? { dispatcher } : {};
   let cachedToken = null;
+  const responseDeadlines = new WeakMap();
+
+  function timeoutError(phase, deadline, status, deadlineTimer = false) {
+    const expired = deadlineTimer || deadline !== undefined && now() >= deadline;
+    return new IntegrationError(`${label} ${phase} ${expired ? 'deadline exceeded' : 'timed out'}`, {
+      code: expired ? 'INTEGRATION_DEADLINE' : 'INTEGRATION_TIMEOUT',
+      ...(expired ? { stop_reason: 'deadline', deadline } : {}),
+      phase,
+      ...(status === undefined ? {} : { status })
+    });
+  }
 
-  async function token() {
+  // Race as well as abort: injected transports and a stalled response stream may
+  // ignore AbortSignal. The timer covers the complete operation, including reads.
+  async function bounded(operation, deadline, timeout, phase, status) {
+    const started = now();
+    const remaining = deadline === undefined ? timeout : Math.min(timeout, deadline - started);
+    const deadlineTimer = Number.isFinite(deadline) && deadline - started <= timeout;
+    if (remaining <= 0) throw timeoutError(phase, deadline, status);
+    const controller = new AbortController();
+    let timer;
+    const expired = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(timeoutError(phase, deadline, status, deadlineTimer));
+        controller.abort();
+      }, remaining);
+    });
+    try {
+      const result = await Promise.race([expired, operation(controller.signal)]);
+      if (deadline !== undefined && now() >= deadline) throw timeoutError(phase, deadline, status);
+      return result;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async function read(response, limit, deadline, phase = 'response read') {
+    const end = Math.min(deadline ?? Infinity, responseDeadlines.get(response) ?? Infinity);
+    try {
+      return await bounded(signal => readCapped(response, limit, label, signal), end, REQUEST_TIMEOUT_MS, phase, response.status);
+    } catch (error) {
+      discard(response);
+      if (error instanceof IntegrationError) {
+        error.status ??= response.status;
+        error.phase ??= phase;
+      }
+      throw error;
+    }
+  }
+
+  async function token(deadline) {
     if (cachedToken && cachedToken.expiresAt > now()) return cachedToken.value;
+    const end = Math.min(deadline ?? Infinity, now() + TOKEN_TIMEOUT_MS);
     const basic = Buffer.from(`${clientId}:${clientSecret}`, 'utf8').toString('base64');
     let response;
     try {
-      response = await fetchImpl(tokenUrl, {
+      response = await bounded(signal => fetchImpl(tokenUrl, {
         method: 'POST',
         headers: {
           authorization: `Basic ${basic}`,
           'content-type': 'application/x-www-form-urlencoded',
-          accept: 'application/json'
+          accept: 'application/json',
+          'accept-encoding': 'gzip, deflate'
         },
         body: 'grant_type=client_credentials',
         redirect: 'manual',
-        signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
+        signal,
         ...transportOptions
-      });
-    } catch {
-      throw new IntegrationError(`${label} token request failed (network error)`);
+      }), end, TOKEN_TIMEOUT_MS, 'token request');
+    } catch (error) {
+      if (error instanceof IntegrationError) throw error;
+      throw new IntegrationError(`${label} token request failed (network error)`, { phase: 'token request' });
     }
     if (response.status < 200 || response.status > 299) {
-      await response.body?.cancel().catch(() => {});
-      throw new IntegrationError(`${label} token request failed (HTTP ${response.status})`);
+      discard(response);
+      throw new IntegrationError(`${label} token request failed (HTTP ${response.status})`, { status: response.status, phase: 'token request' });
     }
     let payload;
     try {
-      payload = JSON.parse(new TextDecoder().decode(await readCapped(response, 64 * 1024, `${label} token`)));
+      payload = JSON.parse(new TextDecoder().decode(await read(response, 64 * 1024, end, 'token response read')));
     } catch (error) {
       if (error instanceof IntegrationError) throw error;
-      throw new IntegrationError(`${label} token response is not valid JSON`);
+      throw new IntegrationError(`${label} token response is not valid JSON`, { phase: 'token response read' });
     }
     if (typeof payload?.access_token !== 'string' || !payload.access_token) {
-      throw new IntegrationError(`${label} token response has no access_token`);
+      throw new IntegrationError(`${label} token response has no access_token`, { phase: 'token response read' });
     }
     const ttlMs = Number.isFinite(Number(payload.expires_in))
       ? Math.max(0, (Number(payload.expires_in) - 60) * 1000)
@@ -159,28 +293,38 @@ export function createServiceClient({
     return cachedToken.value;
   }
 
-  async function send(target, init) {
+  async function send(target, init, deadline) {
+    const destination = new URL(target);
+    if (destination.origin !== origin || destination.username || destination.password || destination.hash) {
+      throw new IntegrationError(`${label} request escaped the configured tenant`);
+    }
+    const end = Math.min(deadline ?? Infinity, now() + REQUEST_TIMEOUT_MS);
     try {
-      return await fetchImpl(target, {
+      const response = await bounded(signal => fetchImpl(target, {
         ...init,
+        headers: { ...init.headers, 'accept-encoding': 'gzip, deflate' },
         redirect: 'manual',
-        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        signal,
         ...transportOptions
-      });
-    } catch {
-      throw new IntegrationError(`${label} ${init.method} ${new URL(target).pathname} failed (network error or timeout)`);
+      }), end, REQUEST_TIMEOUT_MS, 'HTTP request');
+      cookies?.remember(response.headers, destination);
+      responseDeadlines.set(response, end);
+      return response;
+    } catch (error) {
+      if (error instanceof IntegrationError) throw error;
+      throw new IntegrationError(`${label} ${init.method} ${new URL(target).pathname} failed (network error or timeout)`, { phase: 'HTTP request' });
     }
   }
 
-  async function fetchCsrf(bearer) {
+  async function fetchCsrf(bearer, deadline) {
     const response = await send(new URL(`${url}${csrfPath}`).href, {
       method: 'GET',
       headers: { authorization: `Bearer ${bearer}`, 'x-csrf-token': 'Fetch', accept: 'application/json' }
-    });
-    await response.body?.cancel().catch(() => {});
+    }, deadline);
+    discard(response);
     const csrfToken = response.headers.get('x-csrf-token');
-    if (!csrfToken || csrfToken.toLowerCase() === 'required') {
-      throw new IntegrationError(`${label} CSRF token fetch failed (HTTP ${response.status})`);
+    if (response.status < 200 || response.status >= 300 || !csrfToken || csrfToken.toLowerCase() === 'required') {
+      throw new IntegrationError(`${label} CSRF token fetch failed (HTTP ${response.status})`, { status: response.status, phase: 'CSRF request' });
     }
     return { csrfToken, cookies: setCookiePairs(response.headers) };
   }
@@ -194,15 +338,24 @@ export function createServiceClient({
     expect = [200],
     responseType = 'json',
     withStatus = false,
-    unwrap = true
+    unwrap = true,
+    deadline,
+    responseHeaders
   } = {}) {
+    if (deadline !== undefined && !Number.isFinite(deadline)) throw new IntegrationError(`${label} request deadline must be an absolute finite timestamp`);
+    if (deadline !== undefined && now() >= deadline) throw timeoutError('request', deadline);
+    if (responseHeaders !== undefined && (!Array.isArray(responseHeaders)
+      || responseHeaders.some(name => typeof name !== 'string' || !PAGINATION_HEADERS.has(name.toLowerCase())))) {
+      throw new IntegrationError(`${label} response headers are limited to documented pagination tokens`);
+    }
     const target = new URL(`${url}${path}`);
     for (const [key, value] of Object.entries(query || {})) {
       if (value !== undefined && value !== null) target.searchParams.set(key, String(value));
     }
-    // URLSearchParams emits '+' for spaces; OData servers expect %20. Literal '+' is already %2B.
-    target.search = target.search.replaceAll('+', '%20');
-    if (target.origin !== origin) throw new IntegrationError(`${label} request escaped the configured tenant`);
+    // SAP management endpoints require literal OData '$' option names and '%20' spaces.
+    // Decode only a leading '$' in parameter names; values stay encoded (including '+' and '&').
+    target.search = target.search.replaceAll('+', '%20').replace(/([?&])%24(?=[A-Za-z_])/gi, (_, separator) => `${separator}$`);
+    if (target.origin !== origin || target.username || target.password || target.hash) throw new IntegrationError(`${label} request escaped the configured tenant`);
 
     const baseHeaders = { accept };
     let payload;
@@ -223,28 +376,48 @@ export function createServiceClient({
     let csrfRetried = false;
     let serverRetries = 0;
     for (;;) {
-      const headers = { ...baseHeaders, authorization: `Bearer ${await token()}` };
+      let authentication;
+      if (oauth) authentication = `Bearer ${await token(deadline)}`;
+      else {
+        try {
+          authentication = await bounded(() => authorization({ method, path: target.pathname }), deadline, REQUEST_TIMEOUT_MS, 'authorization');
+        } catch (error) {
+          if (error instanceof IntegrationError && error.code === 'INTEGRATION_DEADLINE') throw error;
+          throw new IntegrationError(`${label} private authorization failed`, { phase: 'authorization' });
+        }
+        if (typeof authentication !== 'string' || !authentication || /[^\x20-\x7e]/.test(authentication)) {
+          throw new IntegrationError(`${label} private authorization is invalid`, { phase: 'authorization' });
+        }
+      }
+      const headers = { ...baseHeaders, authorization: authentication };
+      const cookieHeader = cookies?.header(target);
+      if (cookieHeader) headers.cookie = cookieHeader;
       if (csrf) {
         headers['x-csrf-token'] = csrf.csrfToken;
         if (csrf.cookies.length) headers.cookie = csrf.cookies.join('; ');
       }
-      response = await send(target.href, { method, headers, body: payload });
-      if (response.status === 401 && !authRetried) {
+      response = await send(target.href, { method, headers, body: payload }, deadline);
+      if (oauth && response.status === 401 && !authRetried) {
         authRetried = true;
-        await response.body?.cancel().catch(() => {});
+        discard(response);
         cachedToken = null;
         continue;
       }
-      if (response.status === 403 && !csrfRetried && (response.headers.get('x-csrf-token') || '').toLowerCase() === 'required') {
+      if (oauth && response.status === 403 && !csrfRetried && (response.headers.get('x-csrf-token') || '').toLowerCase() === 'required') {
         csrfRetried = true;
-        await response.body?.cancel().catch(() => {});
-        csrf = await fetchCsrf(await token());
+        discard(response);
+        csrf = await fetchCsrf(await token(deadline), deadline);
         continue;
       }
       if (RETRYABLE_METHODS.has(method) && RETRYABLE_STATUS.has(response.status) && !expect.includes(response.status) && serverRetries < SERVER_RETRIES) {
         serverRetries += 1;
-        await response.body?.cancel().catch(() => {});
-        await new Promise(resolve => setTimeout(resolve, retryDelayMs * serverRetries));
+        discard(response);
+        // Scheduling a backoff late is not a timeout; retain the normal request
+        // timeout and any caller deadline instead of racing the delay itself.
+        await bounded(signal => new Promise(resolve => {
+          const timer = setTimeout(resolve, retryDelayMs * serverRetries);
+          signal.addEventListener('abort', () => clearTimeout(timer), { once: true });
+        }), deadline, REQUEST_TIMEOUT_MS, 'retry delay', response.status);
         continue;
       }
       break;
@@ -252,31 +425,46 @@ export function createServiceClient({
 
     if (!expect.includes(response.status)) {
       let detail = '';
-      try {
-        detail = diagnosticText(sapMessage(new TextDecoder().decode(await readCapped(response, MAX_TEXT, label))), 400);
-      } catch {
-        detail = 'response body unavailable';
+      if (!exposeErrorDetails) {
+        discard(response);
+        detail = 'response body withheld to protect credentials';
+      } else {
+        try {
+          detail = diagnosticText(sapMessage(new TextDecoder().decode(await read(response, MAX_TEXT, deadline))), 400);
+        } catch (error) {
+          if (error?.stop_reason === 'deadline') throw error;
+          detail = 'response body unavailable';
+        }
       }
-      throw new IntegrationError(`${label} ${method} ${target.pathname} failed (HTTP ${response.status}): ${detail}`);
+      throw new IntegrationError(`${label} ${method} ${target.pathname} failed (HTTP ${response.status}): ${detail}`, { status: response.status, phase: 'HTTP response' });
     }
     const status = response.status;
-    const wrap = data => (withStatus ? { status, data } : data);
-    if (status === 204 || status >= 300) {
-      await response.body?.cancel().catch(() => {});
+    const wrap = data => {
+      if (responseHeaders === undefined) return withStatus ? { status, data } : data;
+      const selected = {};
+      for (const name of responseHeaders) {
+        const normalized = name.toLowerCase();
+        const value = response.headers.get(normalized);
+        if (value !== null) selected[normalized] = value;
+      }
+      return { ...(withStatus ? { status } : {}), data, responseHeaders: selected };
+    };
+    if (responseType === 'none' || status === 204 || status >= 300) {
+      discard(response);
       return wrap(null);
     }
-    if (responseType === 'bytes') return wrap(await readCapped(response, MAX_BYTES, label));
-    const responseText = new TextDecoder().decode(await readCapped(response, MAX_TEXT, label));
+    if (responseType === 'bytes') return wrap(await read(response, MAX_BYTES, deadline));
+    const responseText = new TextDecoder().decode(await read(response, MAX_TEXT, deadline));
     if (responseType === 'text') return wrap(responseText);
     if (!responseText.trim()) return wrap(null);
     let parsed;
     try {
       parsed = JSON.parse(responseText);
     } catch {
-      throw new IntegrationError(`${label} ${method} ${target.pathname} returned a non-JSON response`);
+      throw new IntegrationError(`${label} ${method} ${target.pathname} returned a non-JSON response`, { status, phase: 'response parse' });
     }
     return wrap(unwrap ? parsed?.d?.results ?? parsed?.d ?? parsed : parsed);
   }
 
-  return Object.freeze({ label, request });
+  return Object.freeze({ label, origin, request });
 }

package/src/integration-messaging.mjs

@@ -0,0 +1,118 @@
+// Narrow metadata-only adapters. No message consumption or broker control.
+// GA cloud schema: https://api.solace.dev/cloud/openapi/mission-control.json
+// SEMP schema linked by https://help.pubsub.em.services.cloud.sap/Admin/SEMP/SEMP-API-Ref.htm
+// Session/auth contract: https://help.pubsub.em.services.cloud.sap/Admin/SEMP/SEMP-Security.htm
+import { z } from 'zod';
+import { READ_ONLY_ANNOTATIONS } from './integration-common.mjs';
+import { createCollectionPager, cursorSchema } from './integration-collections.mjs';
+import { IntegrationError } from './integration-http.mjs';
+
+const CLOUD_ROOT = '/api/v2/missionControl';
+const BROKERS = '/eventBrokerServices';
+const identifier = z.string().min(1).max(255).refine(value => !/[\x00-\x1f\x7f]/.test(value) && value !== '.' && value !== '..');
+const paging = z.object({ top: z.number().int().min(1).max(100).default(100), cursor: cursorSchema }).strict();
+const text = value => typeof value === 'string' && value.length <= 255 && !/[\x00-\x1f\x7f]/.test(value) ? value : undefined;
+const safeNames = values => Array.isArray(values) ? values.slice(0, 100).map(text).filter(value => value !== undefined) : undefined;
+const numericBoolean = (row, names) => Object.fromEntries(names.filter(name => typeof row?.[name] === 'boolean' || typeof row?.[name] === 'number' && Number.isFinite(row[name])).map(name => [name, row[name]]));
+const strings = (row, names) => Object.fromEntries(names.filter(name => text(row?.[name]) !== undefined).map(name => [name, row[name]]));
+const failure = error => ({ result: error?.status === 401 ? 'unauthenticated' : error?.status === 403 ? 'forbidden' : [404, 501].includes(error?.status) ? 'unavailable' : 'error', ...(Number.isInteger(error?.status) ? { http_status: error.status } : {}) });
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+function namedData(raw, expectedId, expectedResourceId) {
+  if (!object(raw?.data) || text(raw.data.id) === undefined || raw.data.id !== expectedId) throw new IntegrationError('Named metadata identity is missing or does not match the requested resource');
+  if (expectedResourceId !== undefined && raw.data.resourceId !== undefined && raw.data.resourceId !== expectedResourceId) throw new IntegrationError('Operation resource identity does not match the requested service');
+  return raw.data;
+}
+function broker(row) {
+  return { ...strings(row, ['id', 'name', 'msgVpnName', 'adminState', 'creationState', 'eventBrokerServiceVersion', 'errorId']),
+    ...(text(row?.errorId) !== undefined ? { error_category: 'service_reported_broker_error' } : {}),
+    ...(Array.isArray(row?.ongoingOperationIds) ? { ongoingOperationIds: safeNames(row.ongoingOperationIds) } : {}),
+    ...(Array.isArray(row?.allowedActions) ? { allowedActions: safeNames(row.allowedActions) } : {}) };
+}
+
+export function registerEventMeshTools(register, client) {
+  register('event_mesh_get_queue', 'Inspect standalone Event Mesh queue',
+    'Read named standalone default-plan queue configuration metadata only. This is not Suite-embedded Event Mesh, message consumption, backlog measurement or a health check.',
+    z.object({ name: identifier }).strict(), READ_ONLY_ANNOTATIONS, async ({ name }) => {
+      try {
+        const response = await client.request('GET', `/hub/rest/api/v1/management/messaging/queues/${encodeURIComponent(name)}`, { unwrap: false, withStatus: true });
+        const row = response.data;
+        if (!object(row)) throw new IntegrationError('Expected queue configuration metadata');
+        const properties = Object.keys(row).filter(key => /^[A-Za-z][A-Za-z0-9_]{0,79}$/.test(key) && !/secret|password|token|credential|authorization|payload|messageBody/i.test(key)).sort().slice(0, 100);
+        return { requested_name: name, result: 'ok', http_status: response.status, property_names: properties,
+          configuration: numericBoolean(row, ['maxQueueSizeInBytes', 'maxMessageSizeInBytes', 'maxRedeliveryCount', 'respectTtl', 'enableIngress', 'enableEgress']),
+          scope: 'standalone_default_plan_configuration', runtime_health: 'unverified' };
+      } catch (error) { return { requested_name: name, ...failure(error) }; }
+    });
+}
+
+export function registerAemTools(register, client) {
+  // Translate the shared signed offset cursor to the documented one-based GA page API.
+  // Fixed source pages keep the cursor independent of the caller's output page size.
+  const pager = createCollectionPager(client, { root: CLOUD_ROOT, request: async (_method, path, options) => {
+    const skip = Number(options.query.$skip ?? 0);
+    const pageNumber = Math.floor(skip / 100) + 1;
+    const raw = await client.request('GET', `${CLOUD_ROOT}${path}`, { unwrap: false, query: { pageNumber, pageSize: 100, expand: 'allowedActions', sort: 'name:asc' }, deadline: options.deadline });
+    if (!Array.isArray(raw?.data) || raw.data.length > 100) throw new IntegrationError('Invalid GA event broker collection');
+    // The public OpenAPI leaves meta untyped. Do not guess total fields; an empty source page proves traversal end.
+    return { value: raw.data.slice(skip % 100) };
+  } });
+  register('aem_list_brokers', 'List Advanced Event Mesh brokers',
+    'Read the US GA Mission Control eventBrokerServices collection with allowedActions. Unknown source counts remain null; no broker credentials or health inference.',
+    paging, READ_ONLY_ANNOTATIONS, args => pager.page({ path: BROKERS, query: { expand: 'allowedActions' }, ...args, project: broker, fallback: false, consistency: 'best_effort', identity: 'id' }));
+  register('aem_get_broker', 'Inspect Advanced Event Mesh broker',
+    'Read one GA broker with broker,allowedActions,messageSpoolDetails expansions privately; return only allowlisted identity/state metadata, not endpoints or credentials.',
+    z.object({ service_id: identifier }).strict(), READ_ONLY_ANNOTATIONS, async ({ service_id }) => {
+      try {
+        const raw = await client.request('GET', `${CLOUD_ROOT}${BROKERS}/${encodeURIComponent(service_id)}`, { unwrap: false, query: { expand: 'broker,allowedActions,messageSpoolDetails' } });
+        const row = namedData(raw, service_id);
+        if (!text(row.eventBrokerServiceVersion)) throw new IntegrationError('Named broker metadata is missing the documented service version');
+        return { requested_service_id: service_id, result: 'ok', ...broker(row), runtime_health: 'unverified' };
+      } catch (error) { return { requested_service_id: service_id, ...failure(error) }; }
+    });
+  register('aem_get_broker_operation', 'Inspect Advanced Event Mesh operation',
+    'Read an existing named GA service operation. Preserve observed status without initiating an operation or interpreting free-form error text.',
+    z.object({ service_id: identifier, operation_id: identifier }).strict(), READ_ONLY_ANNOTATIONS, async ({ service_id, operation_id }) => {
+      try {
+        const raw = await client.request('GET', `${CLOUD_ROOT}${BROKERS}/${encodeURIComponent(service_id)}/operations/${encodeURIComponent(operation_id)}`, { unwrap: false });
+        const row = namedData(raw, operation_id, service_id);
+        return { requested_service_id: service_id, requested_operation_id: operation_id, result: 'ok', ...strings(row, ['id', 'operationType', 'status']),
+          ...(text(row.error?.errorId) !== undefined ? { errorId: row.error.errorId, error_category: 'service_reported_operation_error' } : {}) };
+      } catch (error) { return { requested_service_id: service_id, requested_operation_id: operation_id, ...failure(error) }; }
+    });
+}
+
+const QUEUE_NUMBERS = ['spooledMsgCount', 'spooledByteCount', 'maxMsgSpoolUsage', 'msgSpoolUsage', 'maxBindCount', 'ingressEnabled', 'egressEnabled', 'durable', 'respectTtlEnabled', 'redeliveryEnabled', 'maxRedeliveryCount', 'maxTtl', 'txMsgRate', 'rxMsgRate'];
+export function registerAemSempTools(register, client, { sempVpnName } = {}) {
+  const root = '/SEMP/v2/monitor';
+  // Defer validation to invocation so null-client name enumeration is side-effect-free.
+  const collection = () => `/msgVpns/${encodeURIComponent(identifier.parse(sempVpnName))}/queues`;
+  const pager = createCollectionPager(client, { root, request: async (_method, path, options) => {
+    const query = { count: 100, ...(options.query.$skiptoken ? { cursor: options.query.$skiptoken } : {}) };
+    const raw = await client.request('GET', `${root}${path}`, { unwrap: false, query, deadline: options.deadline });
+    if (!Array.isArray(raw?.data) || raw.data.length > 100) throw new IntegrationError('Invalid SEMP queue collection');
+    let next;
+    const link = raw.meta?.paging?.nextPageUri;
+    if (link !== undefined && link !== null && link !== '') {
+      if (typeof link !== 'string') throw new IntegrationError('Invalid SEMP continuation');
+      const target = new URL(link, client.origin);
+      if (target.origin !== client.origin || target.username || target.password || target.hash || target.pathname !== `${root}${path}` || [...target.searchParams.keys()].some(key => !['count', 'cursor'].includes(key)) || target.searchParams.getAll('cursor').length !== 1 || !target.searchParams.get('cursor') || target.searchParams.getAll('count').length > 1 || target.searchParams.has('count') && target.searchParams.get('count') !== '100') throw new IntegrationError('SEMP continuation leaves the configured queue collection');
+      next = `${root}${path}?${new URLSearchParams({ $skiptoken: target.searchParams.get('cursor') })}`;
+    }
+    return { value: raw.data, ...(next ? { '@odata.nextLink': next } : { source_end: true }) };
+  } });
+  register('aem_list_queues', 'List broker-local SEMP queues',
+    'Read configured VPN queue monitor metadata only, using the independent broker Basic client and private reused session. No messages, cloud-token fallback or SEMP proxy.',
+    paging, READ_ONLY_ANNOTATIONS, async args => {
+      try { return await pager.page({ path: collection(), ...args, project: row => ({ ...strings(row, ['queueName', 'msgVpnName']), ...numericBoolean(row, QUEUE_NUMBERS) }), endOfSource: source => source.source_end === true, fallback: false }); }
+      catch (error) {
+        if (error.status === 529 || error.status === 401 || error.status === 403) return { items: [], returned: 0, total: null, complete: false, next_cursor: null, stop_reason: 'source_limit', source_result: { ...failure(error), setup_status: error.status === 529 ? 'no_session_slots' : 'needs_admin_confirmation', required_setup: error.status === 529 ? 'Release broker management sessions or review session limits' : 'Confirm broker Basic authentication and VPN-scoped read-only management permissions; cloud credentials are not a fallback' } };
+        throw error;
+      }
+    });
+}
+
+export function registerMessagingTools(register, { event_mesh, aem, aem_semp } = {}, { sempVpnName } = {}) {
+  if (event_mesh) registerEventMeshTools(register, event_mesh);
+  if (aem) registerAemTools(register, aem);
+  if (aem_semp) registerAemSempTools(register, aem_semp, { sempVpnName });
+}