sap-ai-dev-toolkit 0.9.9918 → 0.9.9921

package/src/cpi-async-monitoring.mjs

@@ -0,0 +1,177 @@
+// Metadata-only diagnosis of CPI asynchronous processing. No queue/store message content is read.
+import { z } from 'zod';
+import { READ_ONLY_ANNOTATIONS, key, top as topSchema } from './integration-common.mjs';
+import { IntegrationError, odataDate } from './integration-http.mjs';
+import { createCollectionPager, cursorSchema, decodeCollection } from './integration-collections.mjs';
+
+const ROOT = '/api/v1';
+const PAGE_BYTES = 88 * 1024;
+const SOURCE_BYTES = 2 * 1024 * 1024;
+const collectionInputs = { top: topSchema(200, 100), cursor: cursorSchema };
+const exactFilters = { integration_flow: z.string().max(200).optional(), visibility: z.string().max(100).optional() };
+const BROKER_NUMBERS = ['Capacity', 'MaxCapacity', 'QueueNumber', 'MaxQueueNumber'];
+const BROKER_FLAGS = ['CapacityOk', 'CapacityWarning', 'CapacityError', 'IsQueuesHigh', 'IsMessageSpoolHigh', 'IsTransactedSessionsHigh', 'IsConsumersHigh', 'IsProducersHigh'];
+const text = value => typeof value === 'string' ? value.slice(0, 512) : null;
+const number = value => (typeof value === 'number' || typeof value === 'string' && /^\d+(?:\.\d+)?$/.test(value)) && Number.isFinite(Number(value)) && Number(value) >= 0 ? Number(value) : null;
+export const normalizeCpiFlag = value => value === true || value === 1 || value === '1' || value === 'true' ? 1
+  : value === false || value === 0 || value === '0' || value === 'false' ? 0 : null;
+const selectText = (row, fields) => Object.fromEntries(fields.filter(field => row?.[field] !== undefined).map(field => [field, text(row[field])]));
+function dates(row, fields) {
+  return Object.fromEntries(fields.filter(field => row?.[field] !== undefined).map(field => {
+    let value;
+    try { value = odataDate(row[field]); } catch { value = null; }
+    return [field, typeof value === 'string' && Number.isFinite(Date.parse(value)) ? new Date(value).toISOString() : null];
+  }));
+}
+export function projectCpiDataStore(row) {
+  return { ...selectText(row, ['DataStoreName', 'IntegrationFlow', 'Type', 'Visibility']),
+    NumberOfMessages: number(row?.NumberOfMessages), NumberOfOverdueMessages: number(row?.NumberOfOverdueMessages) };
+}
+export function projectCpiJmsQueue(row) {
+  const state = number(row?.State);
+  return { ...selectText(row, ['Name', 'Type']), NumbOfMsgs: number(row?.NumbOfMsgs), Size: number(row?.Size),
+    State: state, state: state === 0 ? 'healthy' : state === 1 ? 'warning' : state === 2 ? 'critical' : 'unknown',
+    FillGrade: number(row?.FillGrade), Active: normalizeCpiFlag(row?.Active), Exclusive: normalizeCpiFlag(row?.Exclusive) };
+}
+export function projectCpiVariable(row) {
+  return { ...selectText(row, ['Name', 'VariableName', 'IntegrationFlow', 'Visibility']), ...dates(row, ['UpdatedAt', 'RetainUntil']) };
+}
+function projectEntry(row) {
+  return { ...selectText(row, ['Id', 'Status', 'MessageId']), ...dates(row, ['DueAt', 'CreatedAt', 'RetainUntil']),
+    ...(typeof row?.MessageId === 'string' && row.MessageId ? { message_log_link: 'unverified' } : {}) };
+}
+function sourceFailure(error) {
+  const status = Number.isInteger(error?.status) ? error.status : Number(/HTTP (\d{3})\b/.exec(error?.message ?? '')?.[1]) || null;
+  const stop_reason = error?.code === 'INTEGRATION_DEADLINE' ? 'deadline' : /safe size limit/.test(error?.message ?? '') ? 'source_limit' : null;
+  return { result: status === 401 ? 'unauthenticated' : status === 403 ? 'forbidden' : status === 404 || status === 501 ? 'unavailable' : 'error',
+    ...(status ? { status } : {}), ...(stop_reason ? { stop_reason } : {}) };
+}
+const emptyPage = failure => ({ items: [], returned: 0, total: null, complete: false, next_cursor: null,
+  stop_reason: failure.stop_reason ?? 'source_limit', source_result: failure });
+function service(client) {
+  const request = (method, path, options) => client.request(method, `${ROOT}${path}`, options);
+  return { request, pager: createCollectionPager(client, { root: ROOT, request }) };
+}
+async function pageSafely(pager, options) {
+  try {
+    const page = await pager.page(options);
+    return !page.source_result && !page.complete && !page.next_cursor && ['deadline', 'source_limit'].includes(page.stop_reason)
+      ? { ...page, source_result: { result: 'error', stop_reason: page.stop_reason } } : page;
+  }
+  catch (error) {
+    // Cursor validation is a local input error, not evidence about the tenant.
+    if (/collection cursor/.test(error?.message ?? '')) throw new IntegrationError('Invalid or expired collection cursor; restart the listing');
+    return emptyPage(sourceFailure(error));
+  }
+}
+const matches = ({ integration_flow, visibility }) => row => (integration_flow === undefined || row.IntegrationFlow === integration_flow)
+  && (visibility === undefined || row.Visibility === visibility);
+
+/** Shared bounded metadata helpers; deadline is the transport's absolute internal deadline. */
+export async function readCpiDataStores(client, { top = 100, cursor, integration_flow, visibility, overdue_only = false, deadline } = {}) {
+  const { pager } = service(client);
+  const exact = matches({ integration_flow, visibility });
+  return pageSafely(pager, { path: '/DataStores', mode: 'local', top, cursor, deadline, maxBytes: PAGE_BYTES,
+    identity: { integration_flow, visibility, overdue_only },
+    filter: row => exact(row) && (!overdue_only || number(row.NumberOfOverdueMessages) > 0), project: projectCpiDataStore });
+}
+export async function readCpiVariables(client, { top = 100, cursor, integration_flow, visibility, deadline } = {}) {
+  const { pager } = service(client);
+  return pageSafely(pager, { path: '/Variables', mode: 'local', top, cursor, deadline, maxBytes: PAGE_BYTES,
+    identity: { integration_flow, visibility }, filter: matches({ integration_flow, visibility }), project: projectCpiVariable });
+}
+export async function readCpiDataStoreEntries(client, { data_store, integration_flow, type = '', top = 100, cursor, deadline } = {}) {
+  const { pager, request } = service(client);
+  const path = `/DataStores(DataStoreName=${key(data_store)},IntegrationFlow=${key(integration_flow)},Type=${key(type)})`;
+  // Validate the collection binding before either the parent-metadata or entry request.
+  const entries = await pageSafely(pager, { path: `${path}/Entries`, mode: 'local', top, cursor, deadline,
+    maxBytes: PAGE_BYTES, project: projectEntry });
+  let store = null;
+  let storeResult;
+  try {
+    const raw = await request('GET', path, { unwrap: false, deadline });
+    const row = raw?.d ?? raw;
+    if (!row || Array.isArray(row) || row.DataStoreName !== data_store || row.IntegrationFlow !== integration_flow || row.Type !== type) {
+      throw new IntegrationError('Unexpected data store identity');
+    }
+    store = projectCpiDataStore(row);
+    storeResult = { result: 'ok' };
+  } catch (error) { storeResult = sourceFailure(error); }
+  return { ...entries, store, source_results: { entries: entries.source_result ?? { result: 'ok' }, store: storeResult } };
+}
+export async function readCpiJmsQueues(client, { top = 100, cursor, name, deadline } = {}) {
+  const { pager } = service(client);
+  return pageSafely(pager, { path: '/Queues', mode: 'local', top, cursor, deadline, maxBytes: PAGE_BYTES,
+    identity: { name }, filter: name === undefined ? undefined : row => row.Name === name, project: projectCpiJmsQueue });
+}
+export async function readCpiJmsQueue(client, { name, deadline } = {}) {
+  const page = await readCpiJmsQueues(client, { name, top: 2, deadline });
+  return { name, found: page.items.length === 1 ? true : page.complete && page.items.length === 0 ? false : null,
+    queue: page.items.length === 1 ? page.items[0] : null, complete: page.complete,
+    ...(page.items.length > 1 ? { identity_ambiguous: true } : {}), ...(page.source_result ? { source_result: page.source_result } : {}),
+    stop_reason: page.stop_reason };
+}
+async function brokerSource(request, expand, deadline) {
+  try {
+    const raw = await request('GET', `/JmsBrokers(${key('Broker1')})`, { query: { $expand: expand }, unwrap: false, deadline });
+    if (Buffer.byteLength(JSON.stringify(raw)) > SOURCE_BYTES) throw new IntegrationError('Response exceeds safe size limit');
+    const broker = raw?.d ?? raw;
+    if (!broker || typeof broker !== 'object' || Array.isArray(broker) || !Object.hasOwn(broker, expand)) throw new IntegrationError('Missing broker metadata');
+    const collection = decodeCollection(broker[expand]);
+    return { broker, raw: broker[expand], rows: collection.items,
+      complete: !collection.next && (collection.total === null || collection.total === collection.items.length), source_result: { result: 'ok' } };
+  } catch (error) { return { rows: [], complete: false, source_result: sourceFailure(error) }; }
+}
+export async function readCpiJmsBrokerStatus(client, { deadline } = {}) {
+  const { pager, request } = service(client);
+  const [states, inactive] = await Promise.all(['QueueStates', 'InactiveQueues'].map(expand => brokerSource(request, expand, deadline)));
+  const brokerRow = states.broker ?? inactive.broker;
+  const broker = brokerRow ? Object.fromEntries([
+    ...BROKER_NUMBERS.map(field => [field, number(brokerRow[field])]), ...BROKER_FLAGS.map(field => [field, normalizeCpiFlag(brokerRow[field])])
+  ]) : null;
+  const summarize = async (source, path, filter, project) => {
+    if (source.raw === undefined) return emptyPage(source.source_result);
+    const page = await pageSafely(pager, { path, raw: source.raw, mode: 'local', top: 200, maxBytes: 24 * 1024, deadline,
+      sourceComplete: source.complete, filter, project });
+    // Broker status is a single bounded snapshot, not a resumable list endpoint.
+    return page.next_cursor ? { ...page, next_cursor: null, complete: false, stop_reason: 'source_limit' } : page;
+  };
+  const queueState = row => { const State = number(row.State); return { ...selectText(row, ['Name']), State,
+    state: State === 0 ? 'healthy' : State === 1 ? 'warning' : State === 2 ? 'critical' : 'unknown' }; };
+  const unhealthy = row => number(row.State) === 1 || number(row.State) === 2;
+  const [unhealthyQueues, unknownQueues, stoppedQueues] = await Promise.all([
+    summarize(states, '/JmsBrokers/QueueStates', unhealthy, queueState),
+    summarize(states, '/JmsBrokers/UnknownQueueStates', row => ![0, 1, 2].includes(number(row.State)), queueState),
+    summarize(inactive, '/JmsBrokers/InactiveQueues', undefined, row => ({ ...selectText(row, ['Name']), stopped: true }))
+  ]);
+  return { broker, queue_count: states.complete ? states.rows.length : null,
+    unhealthy_queue_count: states.complete ? states.rows.filter(unhealthy).length : null,
+    unknown_queue_count: states.complete ? states.rows.filter(row => ![0, 1, 2].includes(number(row.State))).length : null,
+    stopped_queue_count: inactive.complete ? inactive.rows.length : null,
+    unhealthy_queues: unhealthyQueues, unknown_queues: unknownQueues, stopped_queues: stoppedQueues,
+    complete: states.complete && inactive.complete && unhealthyQueues.complete && unknownQueues.complete && stoppedQueues.complete,
+    source_results: { queue_states: states.source_result, inactive_queues: inactive.source_result } };
+}
+
+export function registerCpiAsyncMonitoringTools(register, client) {
+  register('cpi_list_data_stores', 'List CPI data stores',
+    'List bounded data store metadata with exact local iFlow/visibility filters and store-reported backlog counts. No query options or message bodies are read.',
+    { ...collectionInputs, ...exactFilters, overdue_only: z.boolean().default(false) }, READ_ONLY_ANNOTATIONS,
+    args => readCpiDataStores(client, args));
+  register('cpi_list_data_store_entries', 'List data store entries',
+    'List bounded entry metadata and separate store-reported backlog counts. Empty integration_flow selects a global store. MessageId links are unverified; no payloads are read.',
+    { data_store: z.string().min(1).max(200), integration_flow: z.string().max(200), type: z.string().max(40).default(''), ...collectionInputs },
+    READ_ONLY_ANNOTATIONS, args => readCpiDataStoreEntries(client, args));
+  register('cpi_list_variables', 'List CPI variables',
+    'List bounded variable metadata with exact local iFlow/visibility filters. No values or OData query options are read.',
+    { ...collectionInputs, ...exactFilters }, READ_ONLY_ANNOTATIONS, args => readCpiVariables(client, args));
+  register('cpi_list_jms_queues', 'List JMS queues',
+    'List bounded JMS queue metadata from /Queues. Unrecognized or missing flags remain unknown; queue message bodies are never read.',
+    collectionInputs, READ_ONLY_ANNOTATIONS, args => readCpiJmsQueues(client, args));
+  register('cpi_get_jms_queue', 'Get JMS queue metadata',
+    'Find one exact queue name in bounded /Queues metadata. No message bodies are read.',
+    { name: z.string().min(1).max(200) }, READ_ONLY_ANNOTATIONS, args => readCpiJmsQueue(client, args));
+  register('cpi_get_jms_broker_status', 'Get JMS broker status',
+    'Read broker capacity/limit flags and independently retrieve warning/critical queue states and stopped queue identities. Missing access remains explicit partial evidence.',
+    {}, READ_ONLY_ANNOTATIONS, args => readCpiJmsBrokerStatus(client, args));
+}

package/src/cpi-content.mjs

@@ -0,0 +1,92 @@
+// Private original archive/configuration reads. Never return this object directly from a tool.
+import { entity, key, pick } from './integration-common.mjs';
+import { createCollectionPager, decodeCollection } from './integration-collections.mjs';
+import { bundleDigest, readBundle, parseProperties, strFromU8 } from './iflow-bundle.mjs';
+import { stateDigest } from './integration-state.mjs';
+import { IntegrationError } from './integration-http.mjs';
+
+export const CPI_BASE = '/api/v1';
+export const CPI_PACKAGE_ARTIFACT_SETS = Object.freeze({
+  iflows: 'IntegrationDesigntimeArtifacts',
+  value_mappings: 'ValueMappingDesigntimeArtifacts',
+  script_collections: 'ScriptCollectionDesigntimeArtifacts',
+  message_mappings: 'MessageMappingDesigntimeArtifacts'
+});
+export const cpiArtifactPath = (id, version = 'active') => `/IntegrationDesigntimeArtifacts(Id=${key(id)},Version=${key(version)})`;
+
+export async function readCpiContent(client, id, version = 'active', { deadline } = {}) {
+  const path = cpiArtifactPath(id, version);
+  const artifact = entity(await client.request('GET', `${CPI_BASE}${path}`, { deadline }));
+  if (!artifact || artifact.Id !== id || typeof artifact.Version !== 'string') throw new IntegrationError('CPI artifact identity/version is unavailable');
+  delete artifact.ArtifactContent;
+  const bytes = await client.request('GET', `${CPI_BASE}${path}/$value`, {
+    responseType: 'bytes', accept: 'application/zip, application/octet-stream', deadline
+  });
+  const files = readBundle(bytes);
+  const configurations = await readCpiConfigurations(client, id, version, { deadline });
+  const names = new Set(configurations.map(entry => entry.ParameterKey));
+  const defaults = files.get('src/main/resources/parameters.prop');
+  for (const name of Object.keys(defaults ? parseProperties(strFromU8(defaults)) : {})) names.add(name);
+  const bundle_sha256 = bundleDigest(files);
+  return { artifact, bytes, files, configurations, bundle_sha256, state_sha256: stateDigest(bundle_sha256, configurations),
+    parameter_names: [...names].sort(), selector: version, resolved_version: artifact.Version };
+}
+
+export async function readCpiConfigurations(client, id, version = 'active', { deadline } = {}) {
+  try {
+    const path = cpiArtifactPath(id, version);
+    const pager = createCollectionPager(client, { root: CPI_BASE });
+    const raw = await client.request('GET', `${CPI_BASE}${path}/Configurations`, { unwrap: false, deadline });
+    const mode = decodeCollection(raw).next ? 'odata' : 'local';
+    const configurations = [];
+    const names = new Set();
+    let cursor;
+    for (let pageNumber = 0; pageNumber < 10; pageNumber += 1) {
+      const page = await pager.page({ path: `${path}/Configurations`, top: 200, cursor, deadline,
+        raw, mode, project: entry => pick(entry, ['ParameterKey', 'ParameterValue', 'DataType']) });
+      for (const entry of page.items) {
+        if (typeof entry.ParameterKey !== 'string' || typeof entry.ParameterValue !== 'string' || typeof entry.DataType !== 'string' || names.has(entry.ParameterKey)) {
+          throw new IntegrationError('CPI configuration response is incomplete or ambiguous');
+        }
+        names.add(entry.ParameterKey);
+        configurations.push(entry);
+      }
+      if (page.complete) return configurations;
+      if (!page.next_cursor) break;
+      cursor = page.next_cursor;
+    }
+    throw new IntegrationError('CPI configurations could not be read completely within the source limit');
+  } catch (error) {
+    // Configurations are private; a failed tenant response can echo their values.
+    const evidence = cpiReleaseFailure(error);
+    throw new IntegrationError(`CPI configuration read is incomplete or failed${evidence.status ? ` (HTTP ${evidence.status})` : ''}; values withheld`,
+      { ...evidence, ...(error?.code === 'INTEGRATION_DEADLINE' ? { code: error.code } : {}) });
+  }
+}
+
+/** Operational failures intentionally omit arbitrary tenant text, which can echo configuration/source. */
+export function cpiReleaseFailure(error) {
+  const status = Number(error?.status);
+  return { result: status === 401 ? 'unauthenticated' : status === 403 ? 'forbidden' : [404, 501].includes(status) ? 'unavailable' : 'error',
+    ...(Number.isInteger(status) && status >= 100 && status <= 599 ? { status } : {}),
+    ...(error?.code === 'INTEGRATION_DEADLINE' ? { stop_reason: 'deadline' } : {}) };
+}
+
+export async function writeCpiConfigurations(client, id, configurations, { deadline } = {}) {
+  // Reserve space for both exact progress and the enclosing mutation outcome before any write.
+  if (Buffer.byteLength(JSON.stringify(configurations.map(entry => entry.ParameterKey))) > 24000) {
+    throw new IntegrationError('CPI configuration parameter names exceed the safe progress-report limit');
+  }
+  const updated = [];
+  for (const parameter of configurations) {
+    try {
+      await client.request('PUT', `${CPI_BASE}${cpiArtifactPath(id)}/$links/Configurations(${key(parameter.ParameterKey)})`, {
+        json: { ParameterValue: parameter.ParameterValue, DataType: parameter.DataType }, expect: [200, 202, 204], responseType: 'none', deadline
+      });
+      updated.push(parameter.ParameterKey);
+    } catch (error) {
+      return { updated, failed: { key: parameter.ParameterKey, ...cpiReleaseFailure(error) } };
+    }
+  }
+  return { updated, failed: null };
+}

package/src/cpi-monitoring.mjs

@@ -0,0 +1,225 @@
+// Payload-free Cloud Integration message monitoring and incident navigation.
+import { z } from 'zod';
+import { READ_ONLY_ANNOTATIONS, ERROR_TEXT_CAP, capText, entity, isoDate, isoToOdataDateTime, key, pick, redactSecrets, timeWindow, top as topSchema } from './integration-common.mjs';
+import { IntegrationError, odataDate, odataKey } from './integration-http.mjs';
+import { createCollectionPager, cursorSchema, decodeCollection } from './integration-collections.mjs';
+import { redactText } from './redact.mjs';
+import { registerCpiAsyncMonitoringTools } from './cpi-async-monitoring.mjs';
+
+export const MESSAGE_STATUSES = Object.freeze(['COMPLETED', 'PROCESSING', 'RETRY', 'ESCALATED', 'FAILED', 'CANCELLED', 'DISCARDED', 'ABANDONED']);
+export const messageGuid = z.string().regex(/^[A-Za-z0-9_-]{10,64}$/);
+export const mplFilterInputs = {
+  iflow_id: z.string().regex(/^[A-Za-z][A-Za-z0-9_.-]{0,99}$/).optional(),
+  correlation_id: z.string().min(1).max(200).optional(),
+  application_message_id: z.string().min(1).max(200).optional(),
+  custom_header: z.object({ name: z.string().min(1).max(200), value: z.string().max(2000) }).strict().optional()
+};
+export const mplListInputs = {
+  ...mplFilterInputs, status: z.enum(MESSAGE_STATUSES).optional(), from: isoDate.optional(), to: isoDate.optional(),
+  top: topSchema(100, 20), cursor: cursorSchema
+};
+const pageInputs = { top: topSchema(200, 100), cursor: cursorSchema };
+const scalarPick = (row, names) => Object.fromEntries(Object.entries(pick(row, names)).filter(([, value]) => value === null || ['string', 'number', 'boolean'].includes(typeof value)));
+const dates = (row, names) => Object.fromEntries(Object.entries(scalarPick(row, names)).map(([name, value]) => [name, odataDate(value)]));
+const time = value => Date.parse(odataDate(value)) || 0;
+const emptyPage = () => ({ items: [], returned: 0, total: null, complete: true, next_cursor: null, stop_reason: 'end' });
+const safeDiagnostic = value => redactText(value).replace(/https?:\/\/[^\s<>"']+/g, text => {
+  try { const url = new URL(text); return `${url.origin}${url.pathname}`; } catch { return '[url withheld]'; }
+});
+const scopeOf = (tool, args) => JSON.stringify([tool, args.iflow_id ?? null, args.status ?? null, args.correlation_id ?? null, args.application_message_id ?? null, args.custom_header?.name ?? null, args.custom_header?.value ?? null]);
+
+/** One exact filter contract for both MPL collections and count sources. */
+export function messageLogQuery(args, window) {
+  return {
+    $filter: [
+      `LogStart ge datetime'${isoToOdataDateTime(window.from)}'`,
+      `LogStart lt datetime'${isoToOdataDateTime(window.to)}'`,
+      args.iflow_id !== undefined && `IntegrationArtifact/Id eq ${odataKey(args.iflow_id)}`,
+      args.status !== undefined && `Status eq ${odataKey(args.status)}`,
+      args.correlation_id !== undefined && `CorrelationId eq ${odataKey(args.correlation_id)}`,
+      args.application_message_id !== undefined && `ApplicationMessageId eq ${odataKey(args.application_message_id)}`
+    ].filter(Boolean).join(' and '),
+    ...(args.custom_header ? { filterCustomHeaderProperties: `${odataKey(args.custom_header.name)} eq ${odataKey(args.custom_header.value)}` } : {})
+  };
+}
+
+/** Allowlist unknown observed status strings, never payload/navigation bodies. */
+export function projectMessageLog(row) {
+  const log = {
+    ...scalarPick(row, ['MessageGuid', 'CorrelationId', 'ApplicationMessageId', 'IntegrationFlowName', 'Status', 'CustomStatus', 'Sender', 'Receiver']),
+    ...dates(row, ['LogStart', 'LogEnd'])
+  };
+  if (row.IntegrationArtifact && typeof row.IntegrationArtifact === 'object') log.IntegrationArtifact = scalarPick(row.IntegrationArtifact, ['Id', 'Type']);
+  for (const name of ['Sender', 'Receiver']) if (typeof log[name] === 'string' && /^https?:\/\//i.test(log[name])) log[name] = safeDiagnostic(log[name]);
+  return log;
+}
+export const projectMessageRun = row => ({
+  ...scalarPick(row, ['Id', 'OverallState', 'LogLevel']),
+  ...dates(row, ['RunStart', 'RunStop'])
+});
+export function projectMessageStep(row) {
+  const error = capText(safeDiagnostic(row.Error ?? ''), 1024);
+  return { ...scalarPick(row, ['StepId', 'ModelStepId', 'Activity', 'Status']), Error: error.text || null, error_truncated: error.truncated, ...dates(row, ['StepStart', 'StepStop']) };
+}
+
+/** Authenticate the cursor before recovering the frozen default window. */
+export function messageLogWindow(pager, args, scope) {
+  if ((args.from === undefined) !== (args.to === undefined)) throw new IntegrationError('from and to must be supplied together');
+  const context = pager.cursorContext(args.cursor, { scope });
+  const supplied = args.from === undefined ? null : timeWindow(args.from, args.to);
+  if (context) {
+    const window = timeWindow(context.window?.from, context.window?.to);
+    if (supplied && (supplied.from !== window.from || supplied.to !== window.to)) throw new IntegrationError('The monitoring window changed; restart the listing');
+    return window;
+  }
+  const now = Date.now();
+  return supplied ?? timeWindow(new Date(now - 86400000).toISOString(), new Date(now).toISOString());
+}
+export async function listMessageLogs(pager, args, { scope = scopeOf('mpl', args), maxBytes = 94 * 1024, deadline } = {}) {
+  const window = messageLogWindow(pager, args, scope);
+  const page = await pager.page({ path: '/MessageProcessingLogs', query: { ...messageLogQuery(args, window), $inlinecount: 'allpages' },
+    top: args.top, cursor: args.cursor, scope, context: { window }, orderBy: 'LogStart desc', identity: 'MessageGuid', consistency: 'best_effort',
+    project: projectMessageLog, maxBytes, deadline });
+  return { ...page, window };
+}
+
+/** Shared named MPL read; callers supply the service-root-pinned GET and pager. */
+export async function getMessageLogSeed(read, guid) {
+  const row = entity(await read(`/MessageProcessingLogs(${key(guid)})`));
+  if (!row || typeof row !== 'object' || Array.isArray(row) || row.MessageGuid !== guid) throw new IntegrationError('Message not found or invalid MPL metadata');
+  if (Buffer.byteLength(JSON.stringify(projectMessageLog(row), null, 2)) > 4096) throw new IntegrationError('MPL identity metadata exceeds the safe size limit');
+  return row;
+}
+
+export async function getMessageLog(read, pager, guid) {
+  const path = `/MessageProcessingLogs(${key(guid)})`;
+  const log = projectMessageLog(await getMessageLogSeed(read, guid));
+  const text = await read(`${path}/ErrorInformation/$value`, { responseType: 'text', accept: '*/*', expect: [200, 204, 404] });
+  const error = capText(safeDiagnostic(text ?? ''), ERROR_TEXT_CAP);
+  const headersPage = await pager.page({ path: `${path}/CustomHeaderProperties`, mode: 'local', top: 200, sourceComplete: false,
+    maxBytes: 60 * 1024, project: row => redactSecrets(scalarPick(row, ['Name', 'Value'])) });
+  return { log, error_information: error.text || null, error_information_truncated: error.truncated,
+    custom_header_properties: headersPage.items, custom_header_properties_complete: headersPage.complete, custom_header_properties_truncated: headersPage.stop_reason !== 'end' };
+}
+
+const sourceFailure = error => ({ result: error?.status === 401 ? 'unauthenticated' : error?.status === 403 ? 'forbidden' : [404, 501].includes(error?.status) ? 'unavailable' : 'error', ...(Number.isInteger(error?.status) ? { status: error.status } : {}), ...(error?.code === 'INTEGRATION_DEADLINE' ? { stop_reason: 'deadline' } : {}) });
+
+/** Exact tenant counts, independently checked with no more than three in flight. */
+export async function getMessageStatistics(client, args, { deadline = Date.now() + 30000 } = {}) {
+  const window = timeWindow(args.from, args.to);
+  const labels = ['total', ...MESSAGE_STATUSES];
+  const counts = {};
+  const checks = {};
+  let next = 0;
+  await Promise.all(Array.from({ length: 3 }, async () => {
+    while (next < labels.length) {
+      const label = labels[next++];
+      try {
+        const text = await client.request('GET', '/api/v1/MessageProcessingLogs/$count', { query: messageLogQuery({ ...args, status: label === 'total' ? undefined : label }, window), responseType: 'text', deadline });
+        if (typeof text !== 'string' || !/^\d+$/.test(text.trim()) || !Number.isSafeInteger(Number(text.trim()))) throw new IntegrationError('Invalid MPL count response');
+        counts[label] = Number(text.trim());
+        checks[label] = { result: 'ok' };
+      } catch (error) { counts[label] = null; checks[label] = sourceFailure(error); }
+    }
+  }));
+  const allCounts = labels.every(label => counts[label] !== null);
+  const classified = allCounts ? MESSAGE_STATUSES.reduce((sum, label) => sum + counts[label], 0) : null;
+  const consistent = allCounts && Number.isSafeInteger(classified) && classified <= counts.total;
+  const complete = allCounts && consistent;
+  return { window, total: counts.total, count_by_status: Object.fromEntries(MESSAGE_STATUSES.map(label => [label, counts[label]])),
+    unclassified: complete ? counts.total - classified : null, checks, complete,
+    coverage: !allCounts ? 'partial' : !consistent ? 'inconsistent' : counts.total === 0 ? 'no_traffic' : 'complete',
+    failure_rate_statuses: ['FAILED', 'ESCALATED', 'ABANDONED'],
+    failure_rate: complete && counts.total > 0 ? (counts.FAILED + counts.ESCALATED + counts.ABANDONED) / counts.total : null };
+}
+
+export function registerCpiMonitoringTools(register, client) {
+  const cpi = (path, options) => client.request('GET', `/api/v1${path}`, options);
+  const pager = createCollectionPager(client, { root: '/api/v1', request: (_method, path, options) => cpi(path, options) });
+  const getSeed = guid => getMessageLogSeed(cpi, guid);
+  async function readRuns(guid) {
+    const raw = await cpi(`/MessageProcessingLogs(${key(guid)})/Runs`, { unwrap: false });
+    const decoded = decodeCollection(raw);
+    return { raw, ...decoded, complete: !decoded.next && decoded.total !== null && decoded.total === decoded.items.length };
+  }
+  register('cpi_list_message_logs', 'List message processing logs',
+    'List bounded MPL metadata in a fixed UTC [from,to) LogStart window of at most 31 days. Supply both timestamps or neither (frozen last 24 hours). Continuations retain that window; traversal is best effort.',
+    mplListInputs, READ_ONLY_ANNOTATIONS, args => listMessageLogs(pager, args));
+
+  register('cpi_get_message_statistics', 'Get message statistics',
+    'Count total and eight known MPL statuses for the exact explicit UTC [from,to) window, at most 31 days. Partial/inconsistent counts have no overall failure rate; zero messages means no traffic.',
+    { ...mplFilterInputs, from: isoDate, to: isoDate }, READ_ONLY_ANNOTATIONS, args => getMessageStatistics(client, args));
+
+  register('cpi_get_message_log', 'Get message processing log',
+    'Read allowlisted MPL metadata, bounded error text and custom header properties. Payload attachments are never read; credential-shaped header values are withheld.',
+    { message_guid: messageGuid }, READ_ONLY_ANNOTATIONS, ({ message_guid }) => getMessageLog(cpi, pager, message_guid));
+
+  register('cpi_list_message_log_runs', 'List message processing runs',
+    'Page bounded run identities and status metadata for one existing message. Missing messages and messages with no runs are distinct. Run navigation completeness remains explicit.',
+    { message_guid: messageGuid, ...pageInputs }, READ_ONLY_ANNOTATIONS, async ({ message_guid, ...args }) => {
+      const scope = `runs:${message_guid}`;
+      pager.validateCursor(args.cursor, { scope });
+      await getSeed(message_guid);
+      const page = await pager.page({ ...args, path: `/MessageProcessingLogs(${key(message_guid)})/Runs`, mode: 'local', sourceComplete: false, scope,
+        sort: (a, b) => time(b.RunStart) - time(a.RunStart), project: projectMessageRun });
+      const noRuns = page.returned === 0 && !page.source_result && (await readRuns(message_guid)).items.length === 0;
+      return { ...page, message_guid, ...(noRuns ? { outcome: 'no_runs' } : {}) };
+    });
+
+  register('cpi_get_message_log_steps', 'Get message processing steps',
+    'Page run-step metadata ordered by start time. An explicit run must belong to the message; omission freezes the latest observed run across pages. Error text is bounded; payloads are never read.',
+    { message_guid: messageGuid, run_id: z.string().min(1).max(200).optional(), ...pageInputs }, READ_ONLY_ANNOTATIONS, async ({ message_guid, run_id, ...args }) => {
+      const scope = JSON.stringify(['steps', message_guid, run_id ?? null]);
+      const context = pager.cursorContext(args.cursor, { scope });
+      await getSeed(message_guid);
+      const runs = await readRuns(message_guid);
+      if (!runs.items.length) return { ...emptyPage(), complete: runs.complete, stop_reason: runs.complete ? 'end' : 'source_limit', outcome: 'no_runs', run: null, message_guid };
+      const selectedId = context?.run_id ?? run_id;
+      const selected = selectedId === undefined ? runs.items.reduce((best, row) => time(row.RunStart) > time(best.RunStart) ? row : best) : runs.items.find(row => String(row.Id) === selectedId);
+      if (!selected) throw new IntegrationError(runs.complete ? 'run_id does not belong to this message' : 'run_id was not found in the bounded message runs; membership is unverified');
+      if (!['string', 'number'].includes(typeof selected.Id) || !String(selected.Id).length || String(selected.Id).length > 200) throw new IntegrationError('Invalid message run identity');
+      const run = projectMessageRun(selected);
+      const metadataBytes = Buffer.byteLength(JSON.stringify({ run, message_guid }, null, 2)) + 1024;
+      if (metadataBytes > 94 * 1024) return { ...emptyPage(), complete: false, stop_reason: 'output_limit', run: null, run_metadata_truncated: true, message_guid };
+      const page = await pager.page({ ...args, path: `/MessageProcessingLogRuns(${key(selected.Id)})/RunSteps`, mode: 'local', sourceComplete: false,
+        scope, context: { run_id: String(selected.Id) }, maxBytes: 95 * 1024 - metadataBytes,
+        sort: (a, b) => time(a.StepStart) - time(b.StepStart), project: projectMessageStep });
+      return { ...page, run, message_guid, runs_complete: runs.complete };
+    });
+
+  register('cpi_trace_message', 'Trace correlated messages',
+    'Follow only the seed message’s exact nonempty CorrelationId inside an explicit UTC [from,to) window. Return bounded message/artifact identities and allowlisted run metadata when present; never infer business-ID or APIM relationships.',
+    { message_guid: messageGuid, from: isoDate, to: isoDate, top: topSchema(100, 20), cursor: cursorSchema }, READ_ONLY_ANNOTATIONS,
+    async ({ message_guid, ...args }) => {
+      const scope = `trace:${message_guid}`;
+      // Invalid or changed cursors must fail before even the seed request.
+      const window = messageLogWindow(pager, args, scope);
+      const context = pager.cursorContext(args.cursor, { scope });
+      const seed = projectMessageLog(await getSeed(message_guid));
+      const correlation = seed.CorrelationId;
+      if (context?.correlation_id !== undefined && context.correlation_id !== correlation) return { ...emptyPage(), complete: false, stop_reason: 'source_changed', window, seed };
+      if (typeof correlation !== 'string' || !correlation.trim()) return { ...emptyPage(), items: [seed], returned: 1, total: 1, stop_reason: 'no_correlation_id', window, seed };
+      const page = await pager.page({ path: '/MessageProcessingLogs', query: { ...messageLogQuery({ correlation_id: correlation }, window), $inlinecount: 'allpages' },
+        top: args.top, cursor: args.cursor, scope, context: { window, correlation_id: correlation }, orderBy: 'LogStart desc', consistency: 'best_effort', identity: 'MessageGuid',
+        project: projectMessageLog, maxBytes: 90 * 1024 });
+      const run_checks = [];
+      // Run identities are independently bounded; unreadable runs never hide healthy message evidence.
+      const items = [];
+      for (const item of page.items) {
+        try {
+          const runs = await readRuns(item.MessageGuid);
+          items.push({ ...item, runs: runs.items.slice(0, 10).map(projectMessageRun), runs_complete: runs.complete && runs.items.length <= 10 });
+          run_checks.push({ message_guid: item.MessageGuid, result: 'ok' });
+        } catch (error) { items.push({ ...item, runs: [], runs_complete: false }); run_checks.push({ message_guid: item.MessageGuid, ...sourceFailure(error) }); }
+      }
+      // Reserve a fixed run budget per page instead of letting ancillary metadata exceed the output envelope.
+      if (Buffer.byteLength(JSON.stringify({ ...page, items, seed, run_checks }, null, 2)) > 95 * 1024) {
+        return { ...page, complete: false, stop_reason: page.stop_reason === 'end' ? 'source_limit' : page.stop_reason, related_messages_complete: page.complete, seed, run_checks: [], runs_omitted: true, window };
+      }
+      const runsComplete = items.every(item => item.runs_complete);
+      return { ...page, complete: page.complete && runsComplete, stop_reason: page.stop_reason === 'end' && !runsComplete ? 'source_limit' : page.stop_reason,
+        related_messages_complete: page.complete, items, seed, run_checks, window };
+    });
+
+  registerCpiAsyncMonitoringTools(register, client);
+}

package/src/cpi-operational.mjs

@@ -0,0 +1,129 @@
+// On-demand management signals, not a background monitor or receiver-side health proof.
+import { z } from 'zod';
+import { READ_ONLY_ANNOTATIONS, isoDate, timeWindow } from './integration-common.mjs';
+import { createCollectionPager } from './integration-collections.mjs';
+import { getMessageStatistics } from './cpi-monitoring.mjs';
+import { readCpiDataStores, readCpiJmsQueues, readCpiJmsBrokerStatus } from './cpi-async-monitoring.mjs';
+import { readCertificateHealth } from './cpi-security.mjs';
+
+const pageFailure = error => ({ result: error?.status === 401 ? 'unauthenticated' : error?.status === 403 ? 'forbidden' : [404, 501].includes(error?.status) ? 'unavailable' : 'error',
+  status: Number.isInteger(error?.status) ? error.status : null,
+  stop_reason: error?.code === 'INTEGRATION_DEADLINE' ? 'deadline' : 'source_limit' });
+
+async function observePages(read, inspect, deadline) {
+  let cursor;
+  let observed = 0;
+  let pages = 0;
+  try {
+    for (;;) {
+      if (Date.now() >= deadline) return { result: 'error', complete: false, observed, stop_reason: 'deadline' };
+      const page = await read(cursor);
+      for (const item of page.items ?? []) { inspect(item); observed += 1; }
+      pages += 1;
+      if (page.source_result && page.source_result.result !== 'ok') return { ...page.source_result, complete: false, observed, stop_reason: page.stop_reason };
+      if (!page.next_cursor) return { result: 'ok', complete: page.complete, observed, stop_reason: page.stop_reason };
+      if (pages >= 20 || observed >= 2000) return { result: 'ok', complete: false, observed, stop_reason: 'source_limit' };
+      cursor = page.next_cursor;
+    }
+  } catch (error) { return { ...pageFailure(error), complete: false, observed }; }
+}
+
+export async function getOperationalSummary(client, args, { summary = {}, deadline = Date.now() + 30000 } = {}) {
+  const window = timeWindow(args.from, args.to);
+  const evaluated_at = new Date().toISOString();
+  const findings = [];
+  let findings_truncated = false;
+  const add = (kind, identity, detail) => {
+    if (findings.length >= 100) { findings_truncated = true; return; }
+    findings.push({ kind, identity: String(identity ?? '').slice(0, 255), ...detail });
+  };
+  let degraded = false;
+  let unknown = false;
+  const targets = args.iflow_ids ? new Set(args.iflow_ids) : null;
+  const runtimeIds = new Set();
+  const runtimePager = createCollectionPager(client, { root: '/api/v1' });
+  const counts = { runtime_errors: 0, queues_warning: 0, queues_critical: 0, queues_stopped: 0, queues_unknown: 0, overdue_stores: 0,
+    overdue_messages: 0, certificates_expired: 0, certificates_not_yet_valid: 0, certificates_expiring: 0, certificates_unknown: 0 };
+  const sources = {};
+  // Independent reads share one deadline; an inaccessible source never hides healthy-source evidence.
+  await Promise.all([
+    (async () => {
+      sources.runtime = await observePages(cursor => runtimePager.page({ path: '/IntegrationRuntimeArtifacts', top: 500, cursor, orderBy: 'Id', deadline,
+        project: row => Object.fromEntries(['Id', 'Version', 'Status'].map(name => [name, typeof row[name] === 'string' ? row[name].slice(0, 200) : null])) }), row => {
+        if (targets && !targets.has(row.Id)) return;
+        runtimeIds.add(row.Id);
+        if (row.Status === 'ERROR') { degraded = true; counts.runtime_errors += 1; add('runtime_error', row.Id, { version: row.Version ?? null, status: row.Status }); }
+        else if (!['STARTED', 'STARTING', 'STOPPING'].includes(row.Status)) unknown = true;
+      }, deadline);
+      if (targets && [...targets].some(id => !runtimeIds.has(id))) unknown = true;
+    })(),
+    (async () => {
+      sources.stores = await observePages(cursor => readCpiDataStores(client, { top: 200, cursor, deadline }), row => {
+        if (targets && row.IntegrationFlow !== '' && !targets.has(row.IntegrationFlow)) return;
+        if (row.NumberOfOverdueMessages === null) unknown = true;
+        else if (row.NumberOfOverdueMessages > 0) {
+          degraded = true; counts.overdue_stores += 1; counts.overdue_messages += row.NumberOfOverdueMessages;
+          add('overdue_store', row.DataStoreName, { integration_flow: row.IntegrationFlow, messages: row.NumberOfMessages, overdue: row.NumberOfOverdueMessages });
+        }
+      }, deadline);
+    })(),
+    (async () => {
+      sources.queues = await observePages(cursor => readCpiJmsQueues(client, { top: 200, cursor, deadline }), row => {
+        if (row.State === 1 || row.State === 2) { degraded = true; counts[row.State === 1 ? 'queues_warning' : 'queues_critical'] += 1; add('queue_state', row.Name, { state: row.state }); }
+        if (row.Active === 0) { degraded = true; counts.queues_stopped += 1; add('stopped_queue', row.Name, { active: 0 }); }
+        if (row.state === 'unknown' || row.Active === null) { unknown = true; counts.queues_unknown += 1; }
+      }, deadline);
+    })(),
+    (async () => {
+      sources.certificates = await observePages(cursor => readCertificateHealth(client, { top: 200, cursor, warning_days: args.certificate_warning_days ?? 30, deadline, evaluated_at }), row => {
+        const validity = row.validity;
+        if (['expired', 'not_yet_valid', 'expiring'].includes(validity)) {
+          degraded = true; counts[`certificates_${validity}`] += 1;
+          add('certificate_validity', row.alias ?? row.Alias, { validity, days_remaining: row.days_remaining ?? null });
+        } else if (validity !== 'valid') { unknown = true; counts.certificates_unknown += 1; }
+      }, deadline);
+    })(),
+    (async () => {
+      try {
+        const broker = await readCpiJmsBrokerStatus(client, { deadline });
+        sources.broker = { source_results: broker.source_results, complete: broker.complete,
+          broker: broker.broker, warning_queue_count: broker.unhealthy_queue_count, stopped_queue_count: broker.stopped_queue_count };
+        if (Object.values(broker.source_results ?? {}).some(source => source.result !== 'ok') || broker.complete !== true) unknown = true;
+        for (const flag of ['CapacityWarning', 'CapacityError', 'IsQueuesHigh', 'IsMessageSpoolHigh', 'IsTransactedSessionsHigh', 'IsConsumersHigh', 'IsProducersHigh']) {
+          if (broker.broker?.[flag] === 1) { degraded = true; add('broker_limit', 'Broker1', { flag }); }
+          else if (broker.broker?.[flag] !== 0) unknown = true;
+        }
+        for (const queue of broker.unhealthy_queues?.items ?? []) {
+          if ([1, 2].includes(queue.State)) { degraded = true; add('broker_queue_state', queue.Name, { state: queue.State }); }
+        }
+        for (const queue of broker.stopped_queues?.items ?? []) { degraded = true; add('broker_stopped_queue', queue.Name, {}); }
+      } catch (error) { sources.broker = { ...pageFailure(error), complete: false }; unknown = true; }
+    })(),
+    (async () => {
+      const statistics = [];
+      for (const iflow_id of args.iflow_ids ?? [undefined]) {
+        const result = await getMessageStatistics(client, { ...window, ...(iflow_id ? { iflow_id } : {}) }, { deadline });
+        statistics.push({ ...(iflow_id ? { iflow_id } : {}), ...result });
+        for (const status of ['FAILED', 'ESCALATED', 'ABANDONED', 'RETRY']) {
+          const count = result.count_by_status[status];
+          if (count > 0) { degraded = true; add('message_status', iflow_id ?? 'tenant', { status, count }); }
+        }
+        if (!result.complete || result.total === 0 || result.unclassified > 0) unknown = true;
+      }
+      sources.messages = { complete: statistics.every(result => result.complete), items: statistics };
+    })()
+  ]);
+  for (const name of ['runtime', 'stores', 'queues', 'certificates']) if (sources[name]?.complete !== true || sources[name]?.result !== 'ok') unknown = true;
+  return { environment: summary.environment ?? 'default', hosts: { cpi: summary.cpi?.host ?? new URL(client.origin).host },
+    evaluated_at, window, iflow_ids: args.iflow_ids ?? null, health_scope: 'observed_management_signals',
+    health: degraded ? 'degraded' : unknown ? 'unknown' : 'no_issues_observed', counts, findings, findings_truncated, sources,
+    continuous_monitoring: 'unverified', receiver_side_processing: 'unverified' };
+}
+
+export function registerCpiOperationalTools(register, client, { summary = {} } = {}) {
+  register('cpi_get_operational_summary', 'Get CPI operational management snapshot',
+    'Read an on-demand bounded snapshot of runtime, exact message counts, JMS limits/stopped queues, overdue stores and certificate validity. No traffic or missing sources is unknown unless an issue already establishes degraded. This is not continuous monitoring or receiver-side health proof.',
+    { from: isoDate, to: isoDate, iflow_ids: z.array(z.string().regex(/^[A-Za-z][A-Za-z0-9_.-]{0,99}$/)).min(1).max(20).optional(),
+      certificate_warning_days: z.number().int().min(1).max(365).default(30) }, READ_ONLY_ANNOTATIONS,
+    args => getOperationalSummary(client, args, { summary }));
+}