sap-ai-dev-toolkit 0.9.9912 → 0.9.9914

package/src/engineering-tools.mjs

@@ -69,6 +69,30 @@ const TOOLS = {
     ['change_set_id'],
     { readOnlyHint: false, destructiveHint: true, idempotentHint: false }
   ),
+  UpdateTable: textTool(
+    'UpdateTable',
+    'Update and activate an existing Z/Y DDIC table from replacement DDL. The current DDL is re-read and compared with expected_source; VSP checks its source hash again under lock. Requires confirmation exactly equal to UPDATE TABLE <TABLE_NAME>.',
+    {
+      table_name: { type: 'string', minLength: 2, maxLength: 30, pattern: '^[ZzYy][A-Za-z0-9_]{1,29}$' },
+      expected_source: { type: 'string', minLength: 1, maxLength: MAX_CHANGE_BYTES },
+      replacement_source: { type: 'string', minLength: 1, maxLength: MAX_CHANGE_BYTES },
+      transport: { type: 'string', minLength: 1 },
+      confirmation: { type: 'string', minLength: 1, description: 'Must exactly equal UPDATE TABLE <TABLE_NAME>.' }
+    },
+    ['table_name', 'expected_source', 'replacement_source', 'confirmation'],
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: false }
+  ),
+  DeleteEmptyDDLS: textTool(
+    'DeleteEmptyDDLS',
+    'Delete only an empty Z/Y DDLS shell. The source is read first and deletion is refused unless it is blank. Requires confirmation exactly equal to DELETE EMPTY DDLS <OBJECT_NAME>.',
+    {
+      name: { type: 'string', minLength: 2, maxLength: 30, pattern: '^[ZzYy][A-Za-z0-9_]{1,29}$' },
+      transport: { type: 'string', minLength: 1 },
+      confirmation: { type: 'string', minLength: 1, description: 'Must exactly equal DELETE EMPTY DDLS <OBJECT_NAME>.' }
+    },
+    ['name', 'confirmation'],
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: false }
+  ),
   CheckTransportReadiness: textTool(
     'CheckTransportReadiness',
     'Collect a transport request and dependency, inactive-object, ABAP Unit, and ATC evidence bundle. Only registered read/check tools are accepted; inspect findings before handoff.',
@@ -237,6 +261,18 @@ function hashSource(source) {
   return createHash('sha256').update(source).digest('hex');
 }
 
+function adtSourceHash(source) {
+  const canonical = source.replace(/\r\n/g, '\n').replace(/\n+$/g, '');
+  return `sha256:${createHash('sha256').update(canonical).digest('hex')}`;
+}
+
+function customerObjectName(value, label) {
+  if (typeof value !== 'string') throw new Error(`${label} must be a customer object name`);
+  const name = value.trim().toUpperCase();
+  if (!/^[ZY][A-Z0-9_]{1,29}$/.test(name)) throw new Error(`${label} must be a Z/Y customer object name of 2–30 letters, digits, or underscores`);
+  return name;
+}
+
 function containsSource(value, source) {
   if (typeof value === 'string') return value === source;
   if (Array.isArray(value)) return value.some(entry => containsSource(entry, source));
@@ -519,6 +555,75 @@ export function createEngineeringTools(entry, upstreamTools, { env = process.env
     });
   }
 
+  if (available.has('GetTable') && available.has('WriteSource')) {
+    add(TOOLS.UpdateTable, async args => {
+      validateObject(args, 'arguments', ['table_name', 'expected_source', 'replacement_source', 'transport', 'confirmation']);
+      const tableName = customerObjectName(args.table_name, 'table_name');
+      if (args.confirmation !== `UPDATE TABLE ${tableName}`) throw new Error(`confirmation must equal UPDATE TABLE ${tableName}`);
+      for (const [label, source] of [['expected_source', args.expected_source], ['replacement_source', args.replacement_source]]) {
+        if (typeof source !== 'string' || !source) throw new Error(`${label} is required`);
+        if (Buffer.byteLength(source, 'utf8') > MAX_CHANGE_BYTES) throw new Error(`${label} exceeds ${MAX_CHANGE_BYTES} bytes`);
+        if (source.split(/\r?\n/).length > 1000) throw new Error(`${label} exceeds the 1,000-line limit`);
+      }
+      if (args.transport !== undefined && (typeof args.transport !== 'string' || !args.transport.trim())) throw new Error('transport must be a nonempty string when supplied');
+      const tableDefinition = /^\s*define\s+table\s+([A-Z0-9_/]+)/im.exec(args.replacement_source);
+      if (!tableDefinition || tableDefinition[1].toUpperCase() !== tableName) throw new Error(`replacement_source must define table ${tableName}`);
+      const expectedHash = adtSourceHash(args.expected_source);
+      if (expectedHash === adtSourceHash(args.replacement_source)) throw new Error('replacement_source does not change the table DDL');
+
+      const currentResult = await remoteTool(entry, 'GetTable', { table_name: tableName }, available, log);
+      const currentSource = sourceFromResult(currentResult);
+      if (currentSource === undefined) throw new Error(`GetTable did not return source for ${tableName}`);
+      const currentHash = adtSourceHash(currentSource);
+      if (currentHash !== expectedHash) throw new Error(`table source changed since review; re-read ${tableName} and prepare a new update`);
+
+      const writeArguments = {
+        object_type: 'TABL',
+        name: tableName,
+        source: args.replacement_source,
+        mode: 'update',
+        expected_source_hash: currentHash,
+        ...(args.transport ? { transport: args.transport.trim() } : {})
+      };
+      const writeResult = await remoteTool(entry, 'WriteSource', writeArguments, available, log);
+      let writeDetails;
+      try {
+        writeDetails = JSON.parse(resultData(writeResult));
+      } catch {
+        throw new Error(`WriteSource returned an unparseable result for ${tableName}; inspect SAP state before retrying`);
+      }
+      if (!object(writeDetails) || writeDetails.success !== true) throw new Error(`WriteSource did not confirm a successful table update for ${tableName}; inspect SAP state before retrying`);
+      return toolJson({
+        status: 'updated',
+        table_name: tableName,
+        expected_source_hash: currentHash,
+        target_source_hash: adtSourceHash(args.replacement_source),
+        result: writeDetails
+      });
+    });
+  }
+
+  if (available.has('GetSource') && available.has('DeleteObject')) {
+    add(TOOLS.DeleteEmptyDDLS, async args => {
+      validateObject(args, 'arguments', ['name', 'transport', 'confirmation']);
+      const name = customerObjectName(args.name, 'name');
+      if (args.confirmation !== `DELETE EMPTY DDLS ${name}`) throw new Error(`confirmation must equal DELETE EMPTY DDLS ${name}`);
+      if (args.transport !== undefined && (typeof args.transport !== 'string' || !args.transport.trim())) throw new Error('transport must be a nonempty string when supplied');
+
+      const sourceResult = await remoteTool(entry, 'GetSource', { object_type: 'DDLS', name, include_context: false }, available, log);
+      const source = sourceFromResult(sourceResult);
+      if (source === undefined) throw new Error(`GetSource did not return source for DDLS ${name}; refusing deletion`);
+      if (source.trim() !== '') throw new Error(`DDLS ${name} is not empty; refusing deletion`);
+
+      const objectUrl = `/sap/bc/adt/ddic/ddl/sources/${encodeURIComponent(name.toLowerCase())}`;
+      await remoteTool(entry, 'DeleteObject', {
+        object_url: objectUrl,
+        ...(args.transport ? { transport: args.transport.trim() } : {})
+      }, available, log);
+      return toolJson({ status: 'deleted', object_type: 'DDLS', name, object_url: objectUrl });
+    });
+  }
+
   if (available.has('GetTransport')) {
     add(TOOLS.CheckTransportReadiness, async args => {
       validateObject(args, 'arguments', ['transport_id', 'checks']);

package/src/iflow-bundle.mjs

@@ -0,0 +1,282 @@
+// Builds Cloud Integration iFlow bundles (zip) for the CPI OData API.
+// Pure: no network. Manifest import headers follow FlashPipe's tenant-verified
+// test artifact (Apache-2.0, see NOTICE).
+import { readFileSync } from 'node:fs';
+import { strFromU8, strToU8, unzipSync, zipSync } from 'fflate';
+import { IntegrationError } from './integration-http.mjs';
+
+export const IFLOW_TEMPLATES = Object.freeze(['https-request-reply-http']);
+
+const IMPORT_PACKAGE = "com.sap.esb.application.services.cxf.interceptor,com.sap.esb.security,com.sap.it.op.agent.api,com.sap.it.op.agent.collector.camel,com.sap.it.op.agent.collector.cxf,com.sap.it.op.agent.mpl,javax.jms,javax.jws,javax.wsdl,javax.xml.bind.annotation,javax.xml.namespace,javax.xml.ws,org.apache.camel;version=\"2.8\",org.apache.camel.builder;version=\"2.8\",org.apache.camel.builder.xml;version=\"2.8\",org.apache.camel.component.cxf,org.apache.camel.model;version=\"2.8\",org.apache.camel.processor;version=\"2.8\",org.apache.camel.processor.aggregate;version=\"2.8\",org.apache.camel.spring.spi;version=\"2.8\",org.apache.commons.logging,org.apache.cxf.binding,org.apache.cxf.binding.soap,org.apache.cxf.binding.soap.spring,org.apache.cxf.bus,org.apache.cxf.bus.resource,org.apache.cxf.bus.spring,org.apache.cxf.buslifecycle,org.apache.cxf.catalog,org.apache.cxf.configuration.jsse;version=\"2.5\",org.apache.cxf.configuration.spring,org.apache.cxf.endpoint,org.apache.cxf.headers,org.apache.cxf.interceptor,org.apache.cxf.management.counters;version=\"2.5\",org.apache.cxf.message,org.apache.cxf.phase,org.apache.cxf.resource,org.apache.cxf.service.factory,org.apache.cxf.service.model,org.apache.cxf.transport,org.apache.cxf.transport.common.gzip,org.apache.cxf.transport.http,org.apache.cxf.transport.http.policy,org.apache.cxf.workqueue,org.apache.cxf.ws.rm.persistence,org.apache.cxf.wsdl11,org.osgi.framework;version=\"1.6.0\",org.slf4j;version=\"1.6\",org.springframework.beans.factory.config;version=\"3.0\",com.sap.esb.camel.security.cms,org.apache.camel.spi,com.sap.esb.webservice.audit.log,com.sap.esb.camel.endpoint.configurator.api,com.sap.esb.camel.jdbc.idempotency.reorg,javax.sql,org.apache.camel.processor.idempotent.jdbc,org.osgi.service.blueprint;version=\"[1.0.0,2.0.0)\"";
+const IMPORT_SERVICE = "com.sap.esb.webservice.audit.log.AuditLogger,com.sap.esb.security.KeyManagerFactory;multiple:=false,com.sap.esb.security.TrustManagerFactory;multiple:=false,javax.sql.DataSource;multiple:=false;filter=\"(dataSourceName=default)\",org.apache.cxf.ws.rm.persistence.RMStore;multiple:=false,com.sap.esb.camel.security.cms.SignatureSplitter;multiple:=false";
+
+const IFLOW_DIR = 'src/main/resources/scenarioflows/integrationflow';
+const PARAMETERS_PROP = 'src/main/resources/parameters.prop';
+const PARAMETERS_PROPDEF = 'src/main/resources/parameters.propdef';
+const MANIFEST_PATH = 'META-INF/MANIFEST.MF';
+const MANIFEST_LINE_BYTES = 70;
+const MAX_IFLW_BYTES = 256 * 1024;
+const MAX_SCRIPT_BYTES = 128 * 1024;
+const MAX_SCRIPTS = 10;
+const MAX_PARAMETERS = 50;
+const SCRIPT_NAME = /^[A-Za-z0-9_.-]{1,80}\.(groovy|gsh|js)$/;
+const PARAMETER_KEY = /^[A-Za-z0-9_. -]{1,100}$/;
+const VERSION = /^(\d+)\.(\d+)\.(\d+)$/;
+
+const templateCache = new Map();
+
+function templateText(template) {
+  if (!IFLOW_TEMPLATES.includes(template)) throw new IntegrationError(`Unknown iFlow template ${template}`);
+  if (!templateCache.has(template)) {
+    templateCache.set(template, readFileSync(new URL(`./integration-templates/${template}.iflw`, import.meta.url), 'utf8'));
+  }
+  return templateCache.get(template);
+}
+
+function utf8Chunks(text, limit) {
+  // Split on UTF-8 byte boundaries without breaking a multi-byte character.
+  const chunks = [];
+  let current = '';
+  let size = 0;
+  for (const char of text) {
+    const width = Buffer.byteLength(char, 'utf8');
+    if (size + width > limit && current) {
+      chunks.push(current);
+      current = '';
+      size = 0;
+    }
+    current += char;
+    size += width;
+  }
+  if (current || !chunks.length) chunks.push(current);
+  return chunks;
+}
+
+/** Serialize ordered [name, value] headers with JAR line wrapping and CRLF endings. */
+export function manifestText(headers) {
+  const lines = [];
+  for (const [name, value] of headers) {
+    const [first, ...rest] = utf8Chunks(`${name}: ${value}`, MANIFEST_LINE_BYTES);
+    lines.push(first);
+    if (rest.length) {
+      const tail = rest.join('');
+      for (const chunk of utf8Chunks(tail, MANIFEST_LINE_BYTES - 1)) lines.push(` ${chunk}`);
+    }
+  }
+  return `${lines.join('\r\n')}\r\n`;
+}
+
+function parseManifest(text) {
+  const unwrapped = text.replace(/\r\n/g, '\n').replace(/\n /g, '');
+  return unwrapped.split('\n').filter(Boolean).map(line => {
+    const index = line.indexOf(': ');
+    return index < 0 ? [line, ''] : [line.slice(0, index), line.slice(index + 2)];
+  });
+}
+
+/** Replace Bundle-Version in a (possibly wrapped) manifest and re-wrap it. */
+export function replaceManifestVersion(text, newVersion) {
+  const headers = parseManifest(text);
+  const entry = headers.find(([name]) => name === 'Bundle-Version');
+  if (entry) entry[1] = newVersion;
+  else headers.push(['Bundle-Version', newVersion]);
+  return manifestText(headers);
+}
+
+export function bumpPatchVersion(version) {
+  const match = VERSION.exec(String(version));
+  if (!match) throw new IntegrationError(`iFlow version ${version} is not x.y.z; update it in the Integration Suite UI first`);
+  return `${match[1]}.${match[2]}.${Number(match[3]) + 1}`;
+}
+
+// Java .properties are read as ISO-8859-1 by CPI (verified live: raw UTF-8 'ü' came back as 'ü'),
+// so everything outside printable ASCII is written as \uXXXX UTF-16 code units, as Properties.store does.
+function escapeProperty(text, isKey) {
+  const value = String(text);
+  let escaped = '';
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    const code = value.charCodeAt(index);
+    if (char === '\\' || char === ':' || char === '=' || char === '#' || char === '!') escaped += `\\${char}`;
+    else if (char === ' ' && (isKey || index === 0)) escaped += '\\ ';
+    else if (char === '\n') escaped += '\\n';
+    else if (char === '\r') escaped += '\\r';
+    else if (char === '\t') escaped += '\\t';
+    else if (code < 0x20 || code > 0x7e) escaped += `\\u${code.toString(16).toUpperCase().padStart(4, '0')}`;
+    else escaped += char;
+  }
+  return escaped;
+}
+
+function unescapeProperty(text) {
+  return text.replace(/\\(?:u([0-9a-fA-F]{4})|(.))/g, (_, hex, char) => {
+    if (hex) return String.fromCharCode(Number.parseInt(hex, 16));
+    return ({ n: '\n', r: '\r', t: '\t', f: '\f' })[char] ?? char;
+  });
+}
+
+/** Serialize a parameter map in Java properties format. */
+export function propertiesText(parameters) {
+  return Object.entries(parameters).map(([key, value]) => `${escapeProperty(key, true)}=${escapeProperty(value, false)}\n`).join('');
+}
+
+/** Parse a Java properties file (key=value lines, comments, escaped separators). */
+export function parseProperties(text) {
+  const result = {};
+  const logical = text.replace(/\r\n/g, '\n').replace(/\\\n[ \t]*/g, '');
+  for (const rawLine of logical.split('\n')) {
+    const line = rawLine.replace(/^[ \t]+/, '');
+    if (!line || line.startsWith('#') || line.startsWith('!')) continue;
+    let index = 0;
+    while (index < line.length) {
+      const char = line[index];
+      if (char === '\\') { index += 2; continue; }
+      if (char === '=' || char === ':' || char === ' ' || char === '\t') break;
+      index += 1;
+    }
+    const key = unescapeProperty(line.slice(0, index));
+    const value = line.slice(index).replace(/^[ \t]*[=:]?[ \t]*/, '');
+    result[key] = unescapeProperty(value);
+  }
+  return result;
+}
+
+function xmlEscape(value) {
+  return String(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
+export function propdefEntry(key) {
+  return `<parameter><key/><name>${xmlEscape(key)}</name><type>xsd:string</type><isRequired>false</isRequired><constraint/><description/><additionalMetadata/></parameter>`;
+}
+
+export function propdefText(keys) {
+  return `<?xml version="1.0" encoding="UTF-8" standalone="no"?><parameters>${keys.map(propdefEntry).join('')}<param_references/></parameters>`;
+}
+
+/** Append propdef entries for keys not yet declared; keeps existing content intact. */
+export function mergePropdef(text, keys) {
+  const declared = new Set([...String(text).matchAll(/<name>([\s\S]*?)<\/name>/g)].map(match => match[1]
+    .replaceAll('&lt;', '<').replaceAll('&gt;', '>').replaceAll('&quot;', '"').replaceAll('&apos;', "'").replaceAll('&amp;', '&')));
+  const missing = keys.filter(key => !declared.has(key));
+  if (!missing.length) return text;
+  if (!text || !text.includes('<parameters')) return propdefText(keys);
+  const entries = missing.map(propdefEntry).join('');
+  if (text.includes('<param_references')) return text.replace('<param_references', `${entries}<param_references`);
+  if (/<parameters\s*\/>/.test(text)) return text.replace(/<parameters\s*\/>/, `<parameters>${entries}</parameters>`);
+  return text.replace('</parameters>', `${entries}</parameters>`);
+}
+
+export function validateParameters(parameters) {
+  const entries = Object.entries(parameters || {});
+  if (entries.length > MAX_PARAMETERS) throw new IntegrationError(`At most ${MAX_PARAMETERS} parameters are supported`);
+  for (const [key, value] of entries) {
+    if (!PARAMETER_KEY.test(key)) throw new IntegrationError(`Parameter key ${JSON.stringify(key).slice(0, 120)} must match ${PARAMETER_KEY.source}`);
+    if (typeof value !== 'string') throw new IntegrationError(`Parameter ${key} must be a string`);
+  }
+  return entries;
+}
+
+function validateScripts(scripts) {
+  if (scripts.length > MAX_SCRIPTS) throw new IntegrationError(`At most ${MAX_SCRIPTS} scripts are supported`);
+  const seen = new Set();
+  for (const script of scripts) {
+    if (!SCRIPT_NAME.test(script?.name || '')) throw new IntegrationError(`Script name must match ${SCRIPT_NAME.source}`);
+    if (seen.has(script.name)) throw new IntegrationError(`Duplicate script ${script.name}`);
+    seen.add(script.name);
+    if (typeof script.content !== 'string' || Buffer.byteLength(script.content, 'utf8') > MAX_SCRIPT_BYTES) {
+      throw new IntegrationError(`Script ${script.name} must be text up to ${MAX_SCRIPT_BYTES / 1024} KiB`);
+    }
+  }
+}
+
+function templateParameterMap(parameters) {
+  if (!parameters || typeof parameters !== 'object') throw new IntegrationError('template_parameters are required for template iFlows');
+  return {
+    Sender_Path: parameters.sender_path,
+    Receiver_Address: parameters.receiver_address,
+    Receiver_Query: parameters.receiver_query ?? '',
+    Receiver_Method: parameters.receiver_method,
+    Receiver_Proxy_Type: parameters.receiver_proxy_type === 'on_premise' ? 'sapcc' : 'default',
+    Receiver_Location_ID: parameters.receiver_location_id ?? '',
+    Receiver_Authentication: parameters.receiver_authentication,
+    Receiver_Credential_Name: parameters.receiver_credential_name ?? '',
+    Receiver_Timeout: String(parameters.receiver_timeout_ms)
+  };
+}
+
+/** Build an iFlow bundle zip from a vetted template or caller-supplied BPMN. */
+export function buildIflowBundle({
+  id,
+  name,
+  description = '',
+  version = '1.0.0',
+  template,
+  templateParameters,
+  iflwXml,
+  scripts = [],
+  parameters = {}
+}) {
+  let iflw;
+  let merged;
+  if (template && template !== 'custom') {
+    iflw = templateText(template);
+    merged = { ...templateParameterMap(templateParameters), ...parameters };
+  } else {
+    if (typeof iflwXml !== 'string' || !iflwXml.includes('<bpmn2:definitions') || Buffer.byteLength(iflwXml, 'utf8') > MAX_IFLW_BYTES) {
+      throw new IntegrationError('iflw_xml must be a BPMN2 iFlow model (bpmn2:definitions) up to 256 KiB');
+    }
+    iflw = iflwXml;
+    merged = { ...parameters };
+  }
+  for (const [key, value] of Object.entries(merged)) {
+    if (value === undefined || value === null) throw new IntegrationError(`Parameter ${key} is required`);
+    merged[key] = String(value);
+  }
+  const parameterEntries = validateParameters(merged);
+  validateScripts(scripts);
+
+  const files = {
+    [MANIFEST_PATH]: strToU8(manifestText([
+      ['Manifest-Version', '1.0'],
+      ['SAP-RuntimeProfile', 'iflmap'],
+      ['Bundle-SymbolicName', `${id}; singleton:=true`],
+      ['Bundle-Name', name],
+      ['Bundle-Version', version],
+      ['Bundle-ManifestVersion', '2'],
+      ['Origin-Bundle-SymbolicName', id],
+      ['SAP-NodeType', 'IFLMAP'],
+      ['Import-Package', IMPORT_PACKAGE],
+      ['Origin-Bundle-Name', name],
+      ['SAP-BundleType', 'IntegrationFlow'],
+      ['Import-Service', IMPORT_SERVICE]
+    ])),
+    'metainfo.prop': strToU8(`description=${String(description).replace(/[\r\n]+/g, ' ')}\n`),
+    [`${IFLOW_DIR}/${id}.iflw`]: strToU8(iflw)
+  };
+  for (const script of scripts) files[`src/main/resources/script/${script.name}`] = strToU8(script.content);
+  if (parameterEntries.length) {
+    files[PARAMETERS_PROP] = strToU8(propertiesText(merged));
+    files[PARAMETERS_PROPDEF] = strToU8(propdefText(parameterEntries.map(([key]) => key)));
+  }
+  return zipSync(files);
+}
+
+/** Unzip a bundle into path → bytes. */
+export function readBundle(bytes) {
+  try {
+    return new Map(Object.entries(unzipSync(bytes)));
+  } catch {
+    throw new IntegrationError('iFlow bundle is not a readable zip archive');
+  }
+}
+
+export function writeBundle(files) {
+  return zipSync(Object.fromEntries(files));
+}
+
+export { strFromU8, strToU8, MANIFEST_PATH, PARAMETERS_PROP, PARAMETERS_PROPDEF };

package/src/integration-common.mjs

@@ -0,0 +1,232 @@
+// Shared plumbing for the Integration Suite MCP tools: result shaping, OData entity cleanup,
+// secret redaction, common input schemas, and a guarded read-only OData GET tool.
+import { z } from 'zod';
+import { INTEGRATION_CONFIG_ERROR } from './integration-config.mjs';
+import { IntegrationError, odataKey } from './integration-http.mjs';
+import { strFromU8 } from './iflow-bundle.mjs';
+
+export const INTEGRATION_MAX_OUTPUT_BYTES = 96 * 1024;
+export const FILE_TEXT_CAP = 48 * 1024;
+export const SINGLE_FILE_CAP = 90 * 1024;
+export const ERROR_TEXT_CAP = 16 * 1024;
+const TEXT_EXTENSIONS = new Set(['.iflw', '.groovy', '.gsh', '.js', '.py', '.xsl', '.xslt', '.xsd', '.wsdl', '.prop', '.propdef', '.mmap', '.json', '.xml', '.MF', '.project', '.edmx']);
+
+export const READ_ONLY_ANNOTATIONS = Object.freeze({ readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true });
+export const CREATE_ANNOTATIONS = Object.freeze({ readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true });
+export const OVERWRITE_ANNOTATIONS = Object.freeze({ readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true });
+
+// ---------------------------------------------------------------- results
+
+function jsonSafe(value, seen = new WeakSet()) {
+  if (typeof value === 'bigint') return value.toString();
+  if (value instanceof Date) return value.toISOString();
+  if (value instanceof Uint8Array) return { type: 'binary', bytes: value.byteLength };
+  if (Array.isArray(value)) return value.map(entry => jsonSafe(entry, seen));
+  if (value && typeof value === 'object') {
+    if (seen.has(value)) return '[circular]';
+    seen.add(value);
+    const result = Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, jsonSafe(entry, seen)]));
+    seen.delete(value);
+    return result;
+  }
+  if (typeof value === 'number' && !Number.isFinite(value)) return String(value);
+  return value;
+}
+
+function jsonText(value) {
+  const text = JSON.stringify(jsonSafe(value), null, 2);
+  if (Buffer.byteLength(text, 'utf8') > INTEGRATION_MAX_OUTPUT_BYTES) {
+    throw new IntegrationError('Integration Suite result is too large to return safely; narrow the request (for example file_path, $select or a smaller top).');
+  }
+  return text;
+}
+
+export function toolError(error) {
+  let message = 'Integration Suite request failed. Check service-key roles and tenant reachability.';
+  if (error?.name === 'IntegrationError' || (typeof error?.message === 'string' && INTEGRATION_CONFIG_ERROR.test(error.message))) {
+    message = error.message;
+  }
+  return { isError: true, content: [{ type: 'text', text: message }] };
+}
+
+export async function resultOf(operation) {
+  try {
+    return { content: [{ type: 'text', text: jsonText(await operation()) }] };
+  } catch (error) {
+    return toolError(error);
+  }
+}
+
+// ---------------------------------------------------------------- helpers
+
+export const key = value => encodeURIComponent(odataKey(value));
+export const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+export function requireConfirmation(actual, expected) {
+  if (actual !== expected) throw new IntegrationError(`confirmation must equal ${expected}`);
+}
+
+export function list(value) {
+  if (Array.isArray(value)) return value;
+  if (Array.isArray(value?.results)) return value.results;
+  return [];
+}
+
+/** Drop OData plumbing (__metadata, deferred navigation links) from an entity. */
+export function entity(value) {
+  if (Array.isArray(value)) return value.map(entity);
+  if (!value || typeof value !== 'object') return value;
+  const result = {};
+  for (const [name, entry] of Object.entries(value)) {
+    if (name.startsWith('__')) continue;
+    if (entry && typeof entry === 'object' && !Array.isArray(entry) && entry.__deferred) continue;
+    result[name] = entry && typeof entry === 'object' && Array.isArray(entry.results) ? entity(entry.results) : entity(entry);
+  }
+  return result;
+}
+
+const PROVIDER_SECRET_KEYS = new Set(['password', 'clientSecret', 'userSecret', 'orgSecret', 'keystorePassword', 'userName', 'clientId']);
+
+/** Remove API provider credential properties (including user and client ids) entirely. */
+export function withoutSecrets(value) {
+  if (Array.isArray(value)) return value.map(withoutSecrets);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.entries(value)
+    .filter(([name]) => !PROVIDER_SECRET_KEYS.has(name))
+    .map(([name, entry]) => [name, withoutSecrets(entry)]));
+}
+
+export const REDACTED = '[redacted]';
+const SECRET_FIELD = /password|secret|passphrase|private_?key|api_?key|app_?key|consumer_?key|secure_?param|access_?token|refresh_?token/i;
+const BINARY_FIELDS = new Set(['ArtifactContent', 'ResourceContent', 'PackageContent', 'CustomTagsConfigurationContent']);
+
+/**
+ * Replace secret-looking values with [redacted] and omit base64 artifact content. Inside an object flagged
+ * encrypted/isEncrypted (APIM key value maps) every nested `value` is redacted as well.
+ */
+export function redactSecrets(value, encrypted = false) {
+  if (Array.isArray(value)) return value.map(entry => redactSecrets(entry, encrypted));
+  if (!value || typeof value !== 'object') return value;
+  const inEncrypted = encrypted || value.encrypted === true || value.isEncrypted === true;
+  const result = {};
+  for (const [name, entry] of Object.entries(value)) {
+    if (BINARY_FIELDS.has(name)) {
+      if (entry !== null && entry !== undefined && entry !== '') result[name] = '[binary omitted]';
+      continue;
+    }
+    if (entry !== null && entry !== undefined && entry !== '' && typeof entry !== 'object'
+      && (SECRET_FIELD.test(name) || (inEncrypted && name === 'value'))) {
+      result[name] = REDACTED;
+      continue;
+    }
+    result[name] = redactSecrets(entry, inEncrypted);
+  }
+  return result;
+}
+
+export function pick(value, names) {
+  return Object.fromEntries(names.filter(name => value?.[name] !== undefined).map(name => [name, value[name]]));
+}
+
+export function capText(text, limit) {
+  if (typeof text !== 'string') return { text, truncated: false };
+  const bytes = Buffer.from(text, 'utf8');
+  if (bytes.byteLength <= limit) return { text, truncated: false };
+  return { text: new TextDecoder().decode(bytes.subarray(0, limit)).replace(/\uFFFD$/, ''), truncated: true };
+}
+
+export function isoToOdataDateTime(value) {
+  return new Date(value).toISOString().slice(0, 19);
+}
+
+function extensionOf(path) {
+  const name = path.slice(path.lastIndexOf('/') + 1);
+  const index = name.lastIndexOf('.');
+  return index < 0 ? '' : name.slice(index);
+}
+
+export function fileEntry(path, bytes, limit) {
+  const entry = { path, bytes: bytes.byteLength };
+  if (TEXT_EXTENSIONS.has(extensionOf(path))) {
+    const { text, truncated } = capText(strFromU8(bytes), limit);
+    entry.text = text;
+    if (truncated) entry.truncated = true;
+  }
+  return entry;
+}
+
+/** Files of an unzipped bundle (Map path → bytes), or one file when filePath is set. */
+export function bundleFiles(bundle, filePath) {
+  if (filePath) {
+    const bytes = bundle.get(filePath);
+    if (!bytes) throw new IntegrationError('file_path not found in the bundle');
+    return { file: fileEntry(filePath, bytes, SINGLE_FILE_CAP) };
+  }
+  return {
+    files: [...bundle.entries()]
+      .filter(([name]) => !name.endsWith('/'))
+      .map(([name, bytes]) => fileEntry(name, bytes, FILE_TEXT_CAP))
+  };
+}
+
+// ---------------------------------------------------------------- schemas
+
+export const confirmation = z.string().min(1).max(300);
+export const isoDate = z.string().max(40).refine(value => !Number.isNaN(Date.parse(value)), 'must be an ISO-8601 date/time');
+export const top = (max = 200, fallback = 100) => z.number().int().min(1).max(max).default(fallback);
+export const secretValue = z.string().min(1).max(4096)
+  .describe('Write-only: sent to the tenant once and never echoed back by any tool.');
+
+// ---------------------------------------------------------------- read-only OData GET
+
+const ODATA_SEGMENT = String.raw`[A-Za-z][A-Za-z0-9_]{0,99}(?:\([^/?#]{0,400}\))?`;
+const ODATA_PATH = new RegExp(String.raw`^(?:/\$metadata|/${ODATA_SEGMENT}(?:/(?:${ODATA_SEGMENT}|\$count))*)$`);
+const ODATA_OPTIONS = ['$filter', '$select', '$expand', '$orderby', '$top', '$skip', '$inlinecount'];
+
+/** Summarize an OData $metadata document into entity sets and function imports. */
+export function metadataSummary(xml) {
+  const attribute = (tag, name) => tag.match(new RegExp(`\\b${name}="([^"]*)"`))?.[1];
+  const entitySets = [...String(xml).matchAll(/<EntitySet\b[^>]*>/g)]
+    .map(([tag]) => ({ name: attribute(tag, 'Name'), entity_type: attribute(tag, 'EntityType') }))
+    .filter(entry => entry.name);
+  const functionImports = [...String(xml).matchAll(/<FunctionImport\b[^>]*>/g)]
+    .map(([tag]) => ({ name: attribute(tag, 'Name'), http_method: attribute(tag, 'm:HttpMethod') ?? null, return_type: attribute(tag, 'ReturnType') ?? null }))
+    .filter(entry => entry.name);
+  return { entity_sets: entitySets, function_imports: functionImports };
+}
+
+/**
+ * Register a guarded read-only GET over one OData service. Media ($value), $batch and $links
+ * are rejected so payloads and binary content stay out of reach; secrets are redacted.
+ */
+export function registerODataReader(register, { name, title, service, request, examples }) {
+  register(name, title,
+    `Read-only GET against the ${service} OData API for entity sets without a dedicated tool. path is relative to the service root, e.g. ${examples}. Use /$metadata to list entity sets and function imports. Media streams ($value), $batch and $links are not allowed; secret-like fields and artifact content are redacted.`,
+    {
+      path: z.string().max(1000).regex(ODATA_PATH, 'must be /$metadata or /EntitySet[(key)][/Navigation...][/$count] without $value, query string or ..')
+        .refine(value => !value.includes('..'), 'must not contain ..'),
+      query: z.record(z.string().regex(/^(?:\$[a-z]+|[A-Za-z][A-Za-z0-9_]{0,40})$/), z.string().max(2000)).optional()
+        .describe(`OData system options (${ODATA_OPTIONS.join(', ')}) and service-specific custom parameters (e.g. keystoreName).`)
+    },
+    READ_ONLY_ANNOTATIONS,
+    async ({ path, query = {} }) => {
+      for (const option of Object.keys(query)) {
+        if (option.startsWith('$') && !ODATA_OPTIONS.includes(option)) throw new IntegrationError(`query option ${option} is not allowed`);
+      }
+      if (path === '/$metadata') {
+        return metadataSummary(await request('GET', path, { accept: 'application/xml', responseType: 'text' }));
+      }
+      if (path.endsWith('/$count')) {
+        const text = await request('GET', path, { query, accept: 'text/plain', responseType: 'text' });
+        return { count: Number(String(text).trim()) };
+      }
+      const parsed = await request('GET', path, { query, unwrap: false });
+      const data = parsed?.d ?? parsed;
+      const total = Number(data?.__count);
+      const results = Array.isArray(data?.results) ? data.results : null;
+      const cleaned = redactSecrets(entity(results ?? data));
+      return results
+        ? { total: Number.isFinite(total) ? total : null, returned: results.length, more: Boolean(data?.__next), results: cleaned }
+        : cleaned;
+    });
+}