sap-ai-dev-toolkit 0.9.9918 → 0.9.9920

package/src/integration-transport.mjs

@@ -0,0 +1,184 @@
+// Read-only source/node evidence. Content Agent assembly and cTMS promotion remain native.
+import { z } from 'zod';
+import { READ_ONLY_ANNOTATIONS, key } from './integration-common.mjs';
+import { createCollectionPager, cursorSchema, decodeCollection } from './integration-collections.mjs';
+import { CPI_BASE, CPI_PACKAGE_ARTIFACT_SETS } from './cpi-content.mjs';
+import { checkReleaseReadiness } from './integration-analysis.mjs';
+import { snapshotEvidenceForTargets } from './integration-release-store.mjs';
+import { capabilityCatalog } from './integration-capabilities.mjs';
+import { IntegrationError } from './integration-http.mjs';
+
+const packageId = z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,59}$/);
+const proxyName = z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,99}$/);
+const artifactId = /^[A-Za-z][A-Za-z0-9_.-]{0,99}$/;
+const version = /^\d+\.\d+\.\d+$/;
+const nodeName = z.string().min(1).max(255).refine(value => !/[\x00-\x1f\x7f]/.test(value));
+const schema = z.object({
+  source_package_ids: z.array(packageId).min(1).max(20).optional(),
+  apim_proxy_names: z.array(proxyName).min(1).max(20).optional(),
+  target_node_name: nodeName
+}).strict().refine(value => value.source_package_ids?.length || value.apim_proxy_names?.length, 'At least one source package or API proxy is required');
+const MAX_MEMBERS = 500;
+const MAX_PAGES = 20;
+const safeText = (value, max = 255) => typeof value === 'string' && value.length <= max && !/[\x00-\x1f\x7f]/.test(value) ? value : null;
+const safeFailure = 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' } : {}) });
+const host = client => { try { return new URL(client?.origin).host; } catch { return null; } };
+
+function nodeProjection(row) {
+  return { id: typeof row?.id === 'string' ? safeText(row.id) : Number.isSafeInteger(row?.id) ? row.id : null,
+    name: safeText(row?.name), upload_eligibility: 'unknown', import_eligibility: 'unknown' };
+}
+
+export async function readCtmsNodes(client, { top = 100, cursor, deadline } = {}) {
+  const pager = createCollectionPager(client, { root: '/v2', request: async (method, path, options) => {
+    const body = await client.request(method, `/v2${path}`, options);
+    if (!Array.isArray(body?.nodes)) throw new IntegrationError('cTMS nodes response is not the documented nodes collection');
+    return { value: body.nodes, '@odata.count': body.nodes.length };
+  } });
+  return pager.page({ path: '/nodes', top, cursor, mode: 'local', deadline, project: nodeProjection });
+}
+
+export function registerCtmsTools(register, client) {
+  register('ctms_list_nodes', 'List Cloud Transport Management nodes',
+    'Read GET /v2/nodes with bounded local paging. Node identity/name access does not establish upload/import eligibility, route, Content Agent, entitlement or target readiness.',
+    z.object({ top: z.number().int().min(1).max(200).default(100), cursor: cursorSchema }).strict(), READ_ONLY_ANNOTATIONS,
+    args => readCtmsNodes(client, args));
+}
+
+async function enumerateGroup(client, package_id, type, remaining, deadline) {
+  if (remaining <= 0) return { items: [], returned: 0, total: null, complete: false, stop_reason: 'source_limit' };
+  const path = `/IntegrationPackages(${key(package_id)})/${CPI_PACKAGE_ARTIFACT_SETS[type]}`;
+  try {
+    const raw = await client.request('GET', `${CPI_BASE}${path}`, { unwrap: false, deadline });
+    // A finite explicit server count is evidence; a capped navigation with no count is not a complete package.
+    const counted = decodeCollection(raw).total !== null;
+    const pager = createCollectionPager(client, { root: CPI_BASE });
+    const items = [], seen = new Set();
+    let cursor, last;
+    for (let index = 0; index < MAX_PAGES; index++) {
+      last = await pager.page({ path, raw, cursor, top: Math.min(200, remaining - items.length), deadline,
+        sourceComplete: counted, consistency: 'best_effort', identity: 'Id',
+        project: row => ({ id: typeof row?.Id === 'string' && artifactId.test(row.Id) ? row.Id : null,
+          version: typeof row?.Version === 'string' && row.Version.length <= 100 && version.test(row.Version) ? row.Version : null }) });
+      for (const row of last.items) {
+        if (!row.id || !row.version || seen.has(row.id)) return { items, returned: items.length, total: last.total, complete: false, stop_reason: 'source_changed_or_invalid_identity' };
+        seen.add(row.id); items.push(row);
+      }
+      if (last.complete || !last.next_cursor || items.length >= remaining) break;
+      cursor = last.next_cursor;
+    }
+    const complete = last.complete && (last.total === null || last.total === items.length);
+    return { items, returned: items.length, total: last.total, complete,
+      stop_reason: complete ? 'end' : last.next_cursor ? 'source_limit' : last.stop_reason,
+      consistency: 'best_effort_not_transactional' };
+  } catch (error) { return { items: [], returned: 0, total: null, complete: false, stop_reason: error?.code === 'INTEGRATION_DEADLINE' ? 'deadline' : 'source_error', source_result: safeFailure(error) }; }
+}
+
+export async function transportReadiness(clients, input, { deadline = Date.now() + 60000, env = process.env, readiness = checkReleaseReadiness, snapshots = snapshotEvidenceForTargets } = {}) {
+  const args = schema.parse(input);
+  const blockers = new Set(), members = [], packages = [];
+  const selectedPackages = [...new Set(args.source_package_ids ?? [])];
+  const selectedProxies = [...new Set(args.apim_proxy_names ?? [])];
+  if (selectedPackages.length && !clients.cpi) blockers.add('cpi_unconfigured');
+  if (selectedProxies.length && !clients.apim) blockers.add('apim_unconfigured');
+  for (const id of selectedPackages) {
+    const groups = {};
+    if (clients.cpi) for (const type of Object.keys(CPI_PACKAGE_ARTIFACT_SETS)) {
+      const group = await enumerateGroup(clients.cpi, id, type, MAX_MEMBERS - members.length, deadline);
+      const { items, ...evidence } = group;
+      groups[type] = evidence;
+      for (const item of items) members.push({ package_id: id, type, ...item });
+      if (!group.complete) blockers.add('source_enumeration_incomplete');
+    }
+    packages.push({ id, groups, complete: Object.keys(groups).length === 4 && Object.values(groups).every(group => group.complete) });
+  }
+  if (!members.length && !selectedProxies.length) blockers.add('no_transportable_members_observed');
+  let node = null, nodes = { result: clients.ctms ? 'ok' : 'unconfigured', complete: false };
+  if (clients.ctms) try {
+    const matches = [];
+    let cursor;
+    for (let index = 0; index < MAX_PAGES; index++) {
+      const page = await readCtmsNodes(clients.ctms, { top: 200, cursor, deadline });
+      matches.push(...page.items.filter(item => item.name === args.target_node_name));
+      nodes.complete = page.complete; nodes.stop_reason = page.stop_reason;
+      if (page.complete || !page.next_cursor) break;
+      cursor = page.next_cursor;
+    }
+    if (matches.length === 1 && matches[0].id !== null) node = matches[0];
+    else blockers.add(matches.length > 1 ? 'target_node_ambiguous' : 'target_node_missing_or_identity_unverified');
+  } catch (error) { nodes = { ...safeFailure(error), complete: false }; }
+  if (!nodes.complete) blockers.add('target_node_inventory_unverified');
+
+  const identities = new Map();
+  for (const member of members) {
+    member.kind = member.type === 'iflows' ? 'cpi_iflow' : member.type;
+    if (member.type !== 'iflows') { member.readiness = 'native_review_required'; blockers.add('unchecked_non_iflow_members'); continue; }
+    const prior = identities.get(member.id);
+    if (prior) { blockers.add('duplicate_source_iflow_identity'); member.readiness = 'source_identity_ambiguous'; }
+    else identities.set(member.id, member);
+  }
+  const flows = [...identities.values()];
+  const checked = [];
+  for (let offset = 0; offset < flows.length; offset += 20) {
+    const batch = flows.slice(offset, offset + 20);
+    try {
+      const report = await readiness(clients, { cpi_iflow_ids: batch.map(row => row.id), expected_versions: Object.fromEntries(batch.map(row => [`cpi_iflow:${row.id}`, row.version])) }, { deadline });
+      for (const row of batch) {
+        const evidence = report.items.find(item => item.kind === 'cpi_iflow' && item.id === row.id);
+        if (evidence) { Object.assign(row, projectReadiness(evidence)); checked.push(evidence); }
+        else row.readiness = 'unchecked';
+        if (row.readiness !== 'ready') blockers.add('source_release_checks_not_ready');
+      }
+    } catch (error) {
+      blockers.add('source_release_checks_unavailable');
+      for (const row of batch) Object.assign(row, { readiness: 'unchecked', source_result: safeFailure(error) });
+    }
+  }
+  const proxies = [];
+  if (selectedProxies.length && clients.apim) try {
+    const report = await readiness(clients, { apim_proxy_names: selectedProxies }, { deadline });
+    for (const id of selectedProxies) {
+      const evidence = report.items.find(item => item.kind === 'apim_proxy' && item.id === id);
+      proxies.push(evidence ? { id, ...projectReadiness(evidence) } : { id, readiness: 'unchecked' });
+      if (evidence) checked.push(evidence);
+      if (evidence?.readiness !== 'ready') blockers.add('source_release_checks_not_ready');
+    }
+  } catch (error) { blockers.add('source_release_checks_unavailable'); proxies.push(...selectedProxies.map(id => ({ id, readiness: 'unchecked', source_result: safeFailure(error) }))); }
+
+  const snapshotEvidence = await snapshots(clients, checked.filter(item => item.state_sha256), { env, deadline });
+  for (const target of checked) {
+    if (!target.state_sha256 || !snapshotEvidence.items.some(snapshot => snapshot.targets.some(item => item.kind === target.kind && item.id === target.id && item.state_sha256 === target.state_sha256))) blockers.add('matching_verified_snapshot_required');
+  }
+  if (snapshotEvidence.result !== 'ok') blockers.add('snapshot_evidence_unreadable');
+  if (!snapshotEvidence.complete) blockers.add('snapshot_evidence_incomplete');
+  const ctms = capabilityCatalog({ summary: clients.summary }).ctms;
+  const result = {
+    readiness: blockers.size ? 'blocked' : 'needs_admin_confirmation',
+    evidence_scope: 'observed_source_versions_dependencies_validation_and_private_backups',
+    source_hosts: { cpi: host(clients.cpi), apim: host(clients.apim) }, ctms_host: host(clients.ctms),
+    target_node_name: args.target_node_name, target_node: node, node_inventory: nodes,
+    packages, enumeration_complete: packages.every(item => item.complete), members, api_proxies: proxies,
+    checked_iflows: flows.filter(item => item.readiness !== 'unchecked' && item.state_sha256).length,
+    observed_members: members.length, member_output_complete: true, snapshots: snapshotEvidence,
+    target_verification: 'requires_independent_target_bound_server',
+    native_prerequisites: ['Content Agent assembly in its supported format', 'Source/target destinations and export node', 'Transport route and node eligibility', 'Named request set and separate upload/import authorization'].map(name => ({ name, verification: 'needs_admin_confirmation' })),
+    blockers: [...blockers], native_handoff: ctms.native_handoff, source_links: ctms.source_links, contract_boundaries: ctms.contract_boundaries
+  };
+  while (Buffer.byteLength(JSON.stringify(result, null, 2)) > 94 * 1024 && result.members.length) {
+    result.members.pop(); result.member_output_complete = false;
+  }
+  if (!result.member_output_complete) { result.readiness = 'blocked'; result.blockers.push('member_output_limit'); }
+  return result;
+}
+
+function projectReadiness(item) {
+  return { readiness: item.readiness, checked_version: item.version, bundle_sha256: item.bundle_sha256, state_sha256: item.state_sha256,
+    blockers: item.blockers ?? [], reviews: item.reviews ?? [] };
+}
+
+export function registerIntegrationTransportTools(register, clients = {}, options = {}) {
+  register('integration_transport_readiness', 'Check native integration promotion prerequisites',
+    'Read-only complete bounded package-group traversal, exact observed versions and batches of at most 20 iFlow release checks, APIM checks, private matching snapshots and named cTMS node evidence. Unknown/unchecked members block. Never assembles an MTAR, uploads, imports, resets or claims target readiness; native approvals and independent target-bound verification remain required.',
+    schema, READ_ONLY_ANNOTATIONS, args => transportReadiness(clients, args, options));
+}

package/src/integration-validation.mjs

@@ -0,0 +1,26 @@
+// Private per-client latest completed validation evidence; never initiate validation from readiness.
+const TTL_MS = 15 * 60 * 1000;
+const stores = new WeakMap();
+const identity = (id, version) => JSON.stringify([id, version]);
+
+export function rememberValidation(client, { id, resolved_version, state_sha256, bundle_sha256, passed, matching_state = true }, now = Date.now()) {
+  let entries = stores.get(client);
+  if (!entries) { entries = new Map(); stores.set(client, entries); }
+  for (const [key, entry] of entries) if (now - entry.completed_at_ms >= TTL_MS) entries.delete(key);
+  entries.set(identity(id, resolved_version), { state_sha256, bundle_sha256, passed, matching_state,
+    completed_at: new Date(now).toISOString(), completed_at_ms: now });
+}
+
+export function validationEvidence(client, { id, resolved_version, state_sha256 }, now = Date.now()) {
+  const entries = stores.get(client);
+  const key = identity(id, resolved_version);
+  const entry = entries?.get(key);
+  if (!entry) return { result: 'missing', passed: null };
+  if (now - entry.completed_at_ms >= TTL_MS) {
+    entries.delete(key);
+    return { result: 'expired', passed: null, completed_at: entry.completed_at };
+  }
+  if (!entry.matching_state || entry.state_sha256 !== state_sha256) return { result: 'state_changed', passed: null, completed_at: entry.completed_at };
+  return { result: entry.passed === true ? 'passed' : entry.passed === false ? 'failed' : 'unknown', passed: entry.passed,
+    completed_at: entry.completed_at, expires_at: new Date(entry.completed_at_ms + TTL_MS).toISOString() };
+}

package/src/integration-verify.mjs

@@ -1,117 +1,198 @@
-// Online check of CPI/APIM credentials: sign in, then one read-only request per tool area so a
-// missing role shows up as a named area instead of a failing tool call later. Never writes.
-import { createServiceClient } from './integration-http.mjs';
+// Read-only access evidence. Core access, optional capabilities and entitlement
+// evidence are separate: an endpoint response cannot establish a subscription.
+import { createServiceClient, odataKey } from './integration-http.mjs';
+import { createOptionalClients, verifyOptionalClients } from './integration-optional-tools.mjs';
 
-const CSRF_PATHS = Object.freeze({ CPI: '/api/v1/', APIM: '/apiportal/api/1.0/Management.svc/' });
+const CSRF_PATHS = Object.freeze({ CPI: '/api/v1/', APIM: '/apiportal/api/1.0/Management.svc/', DEVHUB: '/odata/1.0/data.svc/' });
 const APIM_BASE = '/apiportal/api/1.0/Management.svc';
+const VERIFY_TIMEOUT_MS = 30_000;
 
 const PROBES = Object.freeze({
   CPI: [
     { area: 'Packages and iFlows', path: '/api/v1/IntegrationPackages', query: { $top: 1 }, core: true },
     { area: 'Deployed artifacts', path: '/api/v1/IntegrationRuntimeArtifacts', query: { $top: 1 } },
-    { area: 'Message logs', path: '/api/v1/MessageProcessingLogs', query: { $top: 1 } },
+    { area: 'Message logs', path: '/api/v1/MessageProcessingLogs', query: { $top: 1, $select: 'MessageGuid' } },
+    { area: 'MPL counts', path: '/api/v1/MessageProcessingLogs/$count', count: true },
     { area: 'Security material', path: '/api/v1/UserCredentials' },
+    { area: 'OAuth credential metadata', path: '/api/v1/OAuth2ClientCredentials' },
+    { area: 'Keystore validity', path: '/api/v1/KeystoreEntries', query: { keystoreName: 'system' }, validity: true },
     { area: 'Number ranges', path: '/api/v1/NumberRanges' },
     { area: 'Partner Directory', path: '/api/v1/StringParameters', query: { $top: 1 } },
     { area: 'Data stores', path: '/api/v1/DataStores' },
-    { area: 'JMS queues', path: "/api/v1/JmsBrokers('Broker1')" }
+    { area: 'JMS queues', path: "/api/v1/JmsBrokers('Broker1')" },
+    { area: 'Queue metadata', path: '/api/v1/Queues' },
+    { area: 'Variables', path: '/api/v1/Variables' }
   ],
   APIM: [
     { area: 'API proxies', path: `${APIM_BASE}/APIProxies`, query: { $top: 1, $select: 'name' }, core: true },
     { area: 'API providers', path: `${APIM_BASE}/APIProviders`, query: { $top: 1, $select: 'name' } },
     { area: 'API products', path: `${APIM_BASE}/APIProducts`, query: { $top: 1, $select: 'name' } },
     { area: 'Key value maps', path: `${APIM_BASE}/KeyMapEntries`, query: { $top: 1, $select: 'name' } },
-    { area: 'Virtual hosts', path: `${APIM_BASE}/VirtualHosts` }
+    { area: 'Virtual hosts', path: `${APIM_BASE}/VirtualHosts` },
+    { area: 'API analytics', path: '/api/1.0/AnalyticsService/ResultsUTC', query: { $top: 1, $select: 'CreatedTime,CallCount' } }
+  ],
+  DEVHUB: [
+    { area: 'Registered developers', path: '/api/1.0/registrations', query: { type: 'registered' }, core: true }
   ]
 });
 
-// Statuses accepted as answers so they can be classified instead of thrown.
-const OBSERVED = [200, 204, 400, 401, 403, 404, 405, 500, 501, 502, 503, 504];
+// Statuses accepted as answers so they can be classified without exposing bodies.
+const OBSERVED = [200, 204, 400, 401, 403, 404, 405, 429, 500, 501, 502, 503, 504];
 
 function classify(status) {
   if (status >= 200 && status < 300) return { result: 'ok', detail: 'readable' };
-  if (status === 401 || status === 403) return { result: 'forbidden', detail: `HTTP ${status}: the service key lacks the role for this area` };
-  if (status === 404 || status === 501) return { result: 'unavailable', detail: `HTTP ${status}: not available on this tenant or plan` };
+  if (status === 401) return { result: 'unauthenticated', detail: 'HTTP 401: authentication was not accepted after recovery' };
+  if (status === 403) return { result: 'forbidden', detail: 'HTTP 403: access denied; the cause or missing permission is not established' };
+  if (status === 404 || status === 501) return { result: 'unavailable', detail: `HTTP ${status}: endpoint unavailable; activation and entitlement remain unknown` };
   return { result: 'error', detail: `HTTP ${status}` };
 }
 
-/** OAuth clients for the resolved CPI/APIM config (null for an unconfigured side). */
+function rows(text) {
+  try {
+    const parsed = JSON.parse(text);
+    const collection = parsed?.d?.results ?? parsed?.value ?? parsed?.d ?? parsed;
+    return Array.isArray(collection) ? collection : [];
+  } catch {
+    return [];
+  }
+}
+
+function source(probe, status, result, extra = {}) {
+  return { method: 'GET', path: probe.path, status, result, ...extra };
+}
+
+function failed(probe, error) {
+  const status = Number.isInteger(error?.status) ? error.status : null;
+  const tokenFailure = String(error?.phase ?? '').startsWith('token');
+  const classification = error?.stop_reason === 'deadline'
+    ? { result: 'error', detail: 'Verification deadline exceeded', stop_reason: 'deadline' }
+    : status === null ? { result: 'error', detail: 'Request failed without an HTTP response' }
+      : status >= 200 && status < 300 ? { result: 'error', detail: `HTTP ${status}: response processing failed` } : classify(status);
+  // Token HTTP errors are useful setup evidence, but raw response/error bodies are not.
+  if (tokenFailure && status !== null && error?.stop_reason !== 'deadline') classification.detail = `Token request failed (HTTP ${status})`;
+  return {
+    area: probe.area, status, ...classification,
+    source: source(probe, status, classification.result, {
+      ...(tokenFailure ? { phase: 'token' } : {}),
+      ...(error?.stop_reason === 'deadline' ? { stop_reason: 'deadline', deadline: error.deadline } : {})
+    })
+  };
+}
+
+/** Core and optional clients are pinned to this runtime's resolved configuration. */
 export function createIntegrationClients(config, { env = process.env, fetchImpl } = {}) {
   const clientFor = (label, side) => (side
     ? createServiceClient({
-      label,
-      url: side.url,
-      tokenUrl: side.tokenUrl,
-      clientId: side.clientId,
-      clientSecret: side.clientSecret,
-      csrfPath: CSRF_PATHS[label],
-      env,
+      label, url: side.url, tokenUrl: side.tokenUrl, clientId: side.clientId, clientSecret: side.clientSecret,
+      csrfPath: CSRF_PATHS[label], exposeErrorDetails: label !== 'DEVHUB', env,
       ...(fetchImpl ? { fetchImpl } : {})
     })
     : null);
-  return { cpi: clientFor('CPI', config?.cpi), apim: clientFor('APIM', config?.apim) };
+  return { cpi: clientFor('CPI', config?.cpi), apim: clientFor('APIM', config?.apim), devhub: clientFor('DEVHUB', config?.devhub), ...createOptionalClients(config, { env, fetchImpl }) };
 }
 
-// Policies are attached by exporting the proxy bundle (Transport.svc), editing it and re-importing it.
-// The export of an existing proxy proves the read half without writing; no proxy means nothing to test.
-async function policyCheck(client, coreText) {
-  const area = 'Policies (proxy bundle export)';
-  let name;
+async function runProbe(client, probe, deadline) {
   try {
-    const parsed = JSON.parse(coreText);
-    name = (parsed?.d?.results ?? parsed?.d ?? parsed?.value ?? [])[0]?.name;
-  } catch {
-    // Unparseable list: reported as unavailable below.
+    const { status, data } = await client.request('GET', probe.path, {
+      query: probe.query, expect: OBSERVED, withStatus: true,
+      responseType: 'text', accept: probe.count ? 'text/plain' : 'application/json', deadline
+    });
+    let classification = classify(status);
+    if (classification.result === 'ok' && probe.count && !/^\d+$/.test(String(data).trim())) {
+      classification = { result: 'error', detail: 'Count endpoint returned invalid count text' };
+    } else if (classification.result === 'ok' && probe.count && !Number.isSafeInteger(Number(data))) {
+      classification = { result: 'error', detail: 'Count endpoint returned a count outside the safe integer range' };
+    }
+    if (classification.result === 'ok' && probe.validity) {
+      const entries = rows(data);
+      if (!entries.some(entry => entry?.ValidNotBefore !== undefined && entry?.ValidNotAfter !== undefined)) {
+        classification = { result: 'untested', detail: 'No certificate with validity fields exists to test validity metadata' };
+      }
+    }
+    return { area: probe.area, status, ...classification, source: source(probe, status, classification.result), text: data };
+  } catch (error) {
+    return failed(probe, error);
   }
-  if (typeof name !== 'string' || !name) return { area, status: null, result: 'unavailable', detail: 'no API proxy exists yet to test the export with' };
+}
+
+async function policyCheck(client, coreText, deadline) {
+  const probe = { area: 'Policies (proxy bundle export)', path: '/apiportal/api/1.0/Transport.svc/APIProxies' };
+  const name = rows(coreText)[0]?.name;
+  if (typeof name !== 'string' || !name) return {
+    area: probe.area, status: null, result: 'untested', detail: 'No API proxy exists to test bundle export',
+    source: source(probe, null, 'untested')
+  };
   try {
-    const { status, data } = await client.request('GET', '/apiportal/api/1.0/Transport.svc/APIProxies', {
-      query: { name }, expect: OBSERVED, withStatus: true, responseType: 'bytes', accept: 'application/zip, application/octet-stream'
+    const { status, data } = await client.request('GET', probe.path, {
+      query: { name }, expect: OBSERVED, withStatus: true, responseType: 'bytes',
+      accept: 'application/zip, application/octet-stream', deadline
     });
     const zip = data instanceof Uint8Array && data[0] === 0x50 && data[1] === 0x4b;
-    if (status >= 200 && status < 300 && !zip) return { area, status, result: 'error', detail: `HTTP ${status} but the export is not a zip bundle` };
-    return { area, status, ...classify(status) };
+    const classification = status >= 200 && status < 300 && !zip
+      ? { result: 'error', detail: `HTTP ${status} but the export is not a zip bundle` } : classify(status);
+    return { area: probe.area, status, ...classification, source: source(probe, status, classification.result) };
   } catch (error) {
-    return { area, status: null, result: 'error', detail: String(error?.message || 'request failed').slice(0, 300) };
+    return failed(probe, error);
   }
 }
 
-async function verifySide(label, client) {
-  if (!client) return { configured: false };
-  const probes = PROBES[label];
-  const run = async probe => {
-    try {
-      const { status, data } = await client.request('GET', probe.path, { query: probe.query, expect: OBSERVED, withStatus: true, responseType: 'text', accept: 'application/json' });
-      return { area: probe.area, status, ...classify(status), text: data };
-    } catch (error) {
-      return { area: probe.area, status: null, result: 'error', detail: String(error?.message || 'request failed').slice(0, 300) };
-    }
+async function runsCheck(client, messageCheck, deadline) {
+  const probe = { area: 'MPL runs', path: '/api/v1/MessageProcessingLogs' };
+  if (messageCheck.result !== 'ok') return {
+    area: probe.area, status: null, result: 'untested', detail: 'Message-log identity lookup did not succeed',
+    source: source(probe, null, 'untested', { prerequisite_result: messageCheck.result })
+  };
+  const guid = rows(messageCheck.text)[0]?.MessageGuid;
+  if (typeof guid !== 'string' || !guid) return {
+    area: probe.area, status: null, result: 'untested', detail: 'No message exists to test run metadata',
+    source: source(probe, null, 'untested')
   };
-  const { text: coreText, ...core } = await run(probes[0]);
-  // The core probe also fetches the token: a thrown request is a token or network failure, reported once.
-  if (core.status === null) {
-    return { configured: true, signed_in: false, ok: false, error: core.detail, checks: [] };
+  return runProbe(client, { ...probe, path: `/api/v1/MessageProcessingLogs(${encodeURIComponent(odataKey(guid))})/Runs` }, deadline);
+}
+
+async function verifySide(label, client, deadline) {
+  if (!client) return { configured: false, entitlement: 'unknown' };
+  const probes = PROBES[label];
+  const core = await runProbe(client, probes[0], deadline);
+  const { text: coreText, ...coreCheck } = core;
+  const signedIn = core.status !== null && core.result !== 'unauthenticated' && core.source.phase !== 'token';
+  if (!signedIn) {
+    return {
+      configured: true, signed_in: false, ok: false, result: core.result, entitlement: 'unknown',
+      error: core.source.phase === 'token' && core.status !== null ? `${label} token request failed (HTTP ${core.status})` : core.detail,
+      checks: [coreCheck]
+    };
   }
-  const others = probes.slice(1).map(run);
-  if (label === 'APIM' && core.result === 'ok') others.push(policyCheck(client, coreText));
-  const checks = [core, ...(await Promise.all(others)).map(({ text, ...check }) => check)];
-  return { configured: true, signed_in: true, ok: core.result === 'ok', checks };
+  const results = await Promise.all(probes.slice(1).map(probe => runProbe(client, probe, deadline)));
+  if (label === 'APIM' && core.result === 'ok') results.push(await policyCheck(client, coreText, deadline));
+  if (label === 'CPI') results.push(await runsCheck(client, results.find(check => check.area === 'Message logs'), deadline));
+  const checks = [coreCheck, ...results.map(({ text, ...check }) => check)];
+  return { configured: true, signed_in: true, ok: core.result === 'ok', result: core.result, entitlement: 'unknown', checks };
 }
 
-/** Verify the configured sides online; `ok` means every configured side signed in and passed its core read. */
-export async function verifyIntegrationClients({ cpi, apim } = {}) {
-  const [cpiResult, apimResult] = await Promise.all([verifySide('CPI', cpi), verifySide('APIM', apim)]);
-  const sides = [cpiResult, apimResult].filter(side => side.configured);
-  return { ok: sides.length > 0 && sides.every(side => side.ok), cpi: cpiResult, apim: apimResult };
+/** `ok` means every configured core service passed its core read, not whole-lifecycle readiness. */
+export async function verifyIntegrationClients(clients = {}) {
+  const { cpi, apim, devhub } = clients;
+  const deadline = Date.now() + VERIFY_TIMEOUT_MS;
+  const [cpiResult, apimResult, devhubResult, optional] = await Promise.all([
+    verifySide('CPI', cpi, deadline), verifySide('APIM', apim, deadline), verifySide('DEVHUB', devhub, deadline),
+    verifyOptionalClients(clients, { deadline })
+  ]);
+  const sides = [cpiResult, apimResult, devhubResult].filter(side => side.configured);
+  return {
+    ok: sides.length > 0 && sides.every(side => side.ok),
+    ok_scope: 'configured_core_access', entitlement: 'unknown',
+    cpi: cpiResult, apim: apimResult, devhub: devhubResult, ...optional
+  };
 }
 
-/** Human-readable lines for one verified side (no secrets: only host, area names and HTTP statuses). */
+/** Human-readable access lines; no response bodies, object values or personal details. */
 export function verificationLines(label, host, side) {
   if (!side?.configured) return [];
-  if (!side.signed_in) return [`✗ ${label} ${host}: sign-in failed — ${side.error}`];
-  const lines = [side.ok ? `✓ ${label} ${host}: signed in` : `✗ ${label} ${host}: signed in, but ${side.checks[0]?.area ?? 'the core area'} is not readable with this key`];
+  if (!side.signed_in) return [`✗ ${label} ${host}: sign-in not verified — ${side.error}`];
+  const lines = [side.ok ? `✓ ${label} ${host}: core access verified` : `✗ ${label} ${host}: ${side.checks[0]?.area ?? 'the core area'} is not readable with this key`];
   for (const check of side.checks) {
-    const mark = check.result === 'ok' ? '✓' : (check.result === 'unavailable' ? '–' : '✗');
+    const mark = check.result === 'ok' ? '✓' : (['unavailable', 'untested'].includes(check.result) ? '–' : '✗');
     lines.push(`    ${mark} ${check.area}${check.result === 'ok' ? '' : ` — ${check.detail}`}`);
   }
   return lines;

package/src/open-connectors-tools.mjs

@@ -0,0 +1,143 @@
+// Open Connectors platform metadata and the one documented instance enabled-state action.
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { createStaticServiceClient, IntegrationError } from './integration-http.mjs';
+import { createCollectionPager, cursorSchema } from './integration-collections.mjs';
+import { READ_ONLY_ANNOTATIONS, OVERWRITE_ANNOTATIONS, requireConfirmation, top } from './integration-common.mjs';
+
+const ROOT = '/elements/api-v2';
+const SCOPE = 'open_connectors.instances.v1';
+const TTL = 15 * 60 * 1000;
+const SOURCE_LIMIT = 2 * 1024 * 1024;
+const credentials = new WeakMap();
+const id = z.union([z.number().int().positive().max(Number.MAX_SAFE_INTEGER), z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9_-]*$/).refine(value => value !== 'enabled')]);
+const text = z.string().max(512).regex(/^[^\x00-\x1f\x7f]*$/);
+const field = value => text.safeParse(value).success;
+const secret = value => typeof value === 'string' && value.length > 0 && value.length <= 16384 && /^[\x21-\x7e]+$/.test(value) && !value.includes(',');
+const invalid = message => { throw new IntegrationError(`Open Connectors ${message}`); };
+
+/** Config has already passed the host optional-config parser; keep credentials out of client properties. */
+export function createOpenConnectorsClient({ url, userSecret, organizationSecret }, { env, fetchImpl } = {}) {
+  if (!secret(userSecret) || !secret(organizationSecret)) invalid('authorization configuration is invalid');
+  const base = new URL(url);
+  if (!base.pathname.endsWith(ROOT) || base.username || base.password || base.search || base.hash) invalid('service root is invalid');
+  const authorization = `User ${userSecret}, Organization ${organizationSecret}`;
+  const options = { label: 'Open Connectors', url, env, fetchImpl };
+  const client = createStaticServiceClient({ ...options, authorization: () => authorization });
+  credentials.set(client, Object.freeze({ root: base.pathname, action: (token, method) => createStaticServiceClient({ ...options, authorization: request => {
+    if (request.method !== method || request.path !== `${base.pathname}/instances/enabled`) invalid('enabled-state authorization scope is invalid');
+    return `${authorization}, Element ${token}`;
+  } }) }));
+  return client;
+}
+
+function project(row) {
+  if (!row || typeof row !== 'object' || Array.isArray(row) || !id.safeParse(row.id).success
+    || row.name !== undefined && !field(row.name)) invalid('instance metadata has an invalid identity or schema');
+  const result = { id: row.id, ...(row.name !== undefined ? { name: row.name } : {}) };
+  if (row.element !== undefined && row.element !== null) {
+    const value = row.element;
+    if (typeof value !== 'object' || Array.isArray(value) || value.id !== undefined && !id.safeParse(value.id).success
+      || ['key', 'name'].some(key => value[key] !== undefined && !field(value[key]))) invalid('element metadata has an invalid schema');
+    result.element = Object.fromEntries(['id', 'key', 'name'].filter(key => value[key] !== undefined).map(key => [key, value[key]]));
+  }
+  return result;
+}
+
+async function named(client, instanceId, deadline) {
+  const row = await client.request('GET', `/instances/${encodeURIComponent(instanceId)}`, { unwrap: false, deadline });
+  const safe = project(row);
+  if (String(safe.id) !== String(instanceId)) invalid('named instance identity does not match the request');
+  return { row, safe };
+}
+
+function checked(schema, handler) {
+  const input = z.object(schema).strict();
+  return args => {
+    const parsed = input.safeParse(args);
+    if (!parsed.success) invalid('tool input is invalid');
+    return handler(parsed.data);
+  };
+}
+
+export function registerOpenConnectorsTools(register, client) {
+  const root = credentials.get(client)?.root ?? ROOT;
+  const guard = createCollectionPager(client, { root });
+  // Raw server tokens never enter a signed (but readable) cursor. Only random private lookup IDs do.
+  const listings = new Map();
+  async function instances({ top: size, cursor }) {
+    const now = Date.now();
+    for (const [key, value] of listings) if (value.expires <= now) listings.delete(key);
+    const context = cursor ? guard.cursorContext(cursor, { scope: SCOPE }) : randomUUID();
+    let listing = listings.get(context);
+    if (cursor && !listing) invalid('collection cursor is expired; restart the listing');
+    if (!listing) {
+      if (listings.size >= 16) listings.delete(listings.keys().next().value);
+      listing = { expires: now + TTL, pages: new Map([['first', { token: null, prior: [] }]]), bytes: 0 };
+      listings.set(context, listing);
+    }
+    let observed;
+    const pager = createCollectionPager(client, { root, request: async (method, path, options) => {
+      if (method !== 'GET' || path !== '/instances' || Object.keys(options.query).some(key => !['$top', '$skiptoken', '$skip'].includes(key))) invalid('collection request scope is invalid');
+      const key = options.query.$skiptoken ?? 'first';
+      const page = listing.pages.get(key);
+      if (!page || options.query.$skip) invalid('collection continuation is invalid');
+      if (!page.rows) {
+        if (page.end) page.rows = [];
+        else {
+          const source = await client.request('GET', '/instances', { query: { pageSize: 200, ...(page.token === null ? {} : { nextPage: page.token }) }, unwrap: false, responseHeaders: ['elements-next-page-token', 'nextpage'], deadline: options.deadline });
+          if (!Array.isArray(source.data) || source.data.length > 200) invalid('instance collection has an invalid schema or exceeds its page bound');
+          const rows = source.data.map(project);
+          if (new Set(rows.map(row => String(row.id))).size !== rows.length) invalid('instance collection contains duplicate identities');
+          const bytes = Buffer.byteLength(JSON.stringify(rows));
+          if (listing.bytes + bytes > SOURCE_LIMIT) invalid('instance collection exceeds the safe size limit');
+          const tokens = [source.responseHeaders['elements-next-page-token'], source.responseHeaders.nextpage].filter(value => value !== undefined && value !== '');
+          if (tokens.some(value => typeof value !== 'string' || value.length > 4096 || /[\x00-\x20\x7f]/.test(value)) || new Set(tokens).size > 1) invalid('pagination metadata is invalid');
+          const token = tokens[0] ?? null;
+          if (token !== null && (token === page.token || page.prior.includes(token))) invalid('pagination metadata repeats a continuation');
+          if (token !== null && rows.length === 0) invalid('pagination metadata continues an empty page');
+          if (listing.pages.size >= 256) invalid('instance collection exceeds the safe size limit');
+          page.rows = rows;
+          page.terminal = token === null;
+          listing.bytes += bytes;
+          // A private end marker lets the shared pager prove exhaustion without inventing a count.
+          if (rows.length) {
+            page.next = randomUUID();
+            listing.pages.set(page.next, { token, prior: token === null ? [] : [...page.prior, token], end: token === null });
+          }
+        }
+      }
+      observed = page;
+      return { d: { results: page.rows, ...(page.next ? { __next: `${root}/instances?$skiptoken=${page.next}` } : {}) } };
+    } });
+    const result = await pager.page({ path: '/instances', top: size, cursor, scope: SCOPE, context, fallback: false, deadline: now + 30000 });
+    // Absence of the documented token establishes the end; counts remain unknown, never page length.
+    if (observed?.terminal && result.stop_reason === 'more' && result.items.length
+      && String(result.items.at(-1).id) === String(observed.rows.at(-1)?.id)) return { ...result, complete: true, next_cursor: null, stop_reason: 'end' };
+    return result;
+  }
+  const listInput = { top: top(200, 100), cursor: cursorSchema };
+  register('open_connectors_list_instances', 'List Open Connectors instances',
+    'Read bounded instance identities and element metadata only. Tokens, configuration and provider data are withheld. Opaque runtime-bound cursors resume documented nextPage pagination; source totals remain unknown.',
+    listInput, READ_ONLY_ANNOTATIONS, checked(listInput, instances));
+  const getInput = { instance_id: id };
+  register('open_connectors_get_instance', 'Get Open Connectors instance metadata',
+    'Read one exact instance identity and element id/key/name using platform User/Organization authorization. No token, configuration, provider data or provider-health assertion is returned.',
+    getInput, READ_ONLY_ANNOTATIONS, checked(getInput, async ({ instance_id }) => (await named(client, instance_id, Date.now() + 30000)).safe));
+  const actionInput = { instance_id: id, enabled: z.boolean(), confirmation: z.string().max(256) };
+  register('open_connectors_set_instance_enabled', 'Set Open Connectors instance enabled state',
+    'Require exactly ENABLE OPEN CONNECTOR INSTANCE <id> or DISABLE OPEN CONNECTOR INSTANCE <id> before any request. Privately read a fresh instance token, then bodyless PUT (enable) or DELETE (disable) /instances/enabled. DELETE disables, never deletes the instance. HTTP acceptance does not verify effective state or provider health; provider OAuth/re-authentication remains native.',
+    actionInput, OVERWRITE_ANNOTATIONS, checked(actionInput, async ({ instance_id, enabled, confirmation }) => {
+      requireConfirmation(confirmation, `${enabled ? 'ENABLE' : 'DISABLE'} OPEN CONNECTOR INSTANCE ${instance_id}`);
+      const state = credentials.get(client);
+      if (!state) invalid('enabled-state credentials are not configured');
+      const deadline = Date.now() + 30000;
+      const { row } = await named(client, instance_id, deadline);
+      if (!secret(row.token)) invalid('named instance has no usable private token');
+      const method = enabled ? 'PUT' : 'DELETE';
+      const action = state.action(row.token, method);
+      const response = await action.request(method, '/instances/enabled', { expect: Array.from({ length: 100 }, (_, index) => 200 + index), responseType: 'none', withStatus: true, deadline });
+      return { instance_id, requested_enabled: enabled, accepted: true, http_status: response.status,
+        effective_state: 'unverified', provider_health: 'unverified' };
+    }));
+}