sap-ai-dev-toolkit 0.9.9922 → 0.9.9923

package/src/hana-database.mjs

@@ -125,7 +125,7 @@ export class HanaDatabase {
   }
 }
 
-export async function connectReadOnlyHana(config, { driver } = {}) {
+export async function connectHana(config, { driver, queryTimeoutMs } = {}) {
   let selectedDriver = driver;
   if (!selectedDriver) {
     try {
@@ -139,7 +139,7 @@ export async function connectReadOnlyHana(config, { driver } = {}) {
   }
 
   const connection = selectedDriver.createConnection();
-  const database = new HanaDatabase(connection, config);
+  const database = new HanaDatabase(connection, config, { queryTimeoutMs });
   try {
     await database.connect();
     return database;
@@ -147,4 +147,4 @@ export async function connectReadOnlyHana(config, { driver } = {}) {
     await database.close();
     throw error;
   }
-}
+}

package/src/hana-inspector.mjs

@@ -4,7 +4,7 @@ import { pathToFileURL } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { resolveHanaReadOnlyConfig } from './hana-config.mjs';
-import { connectReadOnlyHana } from './hana-database.mjs';
+import { connectHana } from './hana-database.mjs';
 import { registerHanaTools } from './hana-tools.mjs';
 
 const packageMetadata = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
@@ -21,7 +21,7 @@ function publicConnectionSummary(config) {
 }
 
 /** Create an injectable server runtime for tests and the stdio executable. */
-export function createHanaInspector({ env = process.env, driver, databaseFactory = connectReadOnlyHana } = {}) {
+export function createHanaInspector({ env = process.env, driver, databaseFactory = connectHana } = {}) {
   const config = resolveHanaReadOnlyConfig(env);
   const summary = publicConnectionSummary(config);
   let databasePromise;

package/src/harnesses.mjs

@@ -92,6 +92,36 @@ User request: $ARGUMENTS
 `);
 }
 
+const OMP_HOST_NOTE = '**OMP host note.** OMP starts the MCP servers configured in its `mcp.json` and exposes each tool in this session\'s tool inventory as `mcp__<server>_<tool>` (for example `mcp__<server>_get_source`); tools listed only as `xd://` tool devices are called by writing their JSON arguments to that path after reading its docs. Treat that inventory as the live `tools/list` referenced below. The other bundled SAP agents are installed as OMP task agents named after their kebab-case ids (for example `abap-developer`, `sap-integration-developer`); hand work to them with the `task` tool when a handoff is required.';
+
+export function ompAgentName(fileName) {
+  return String(fileName).replace(/\.agent\.md$/, '').replace(/\.md$/, '');
+}
+
+export function ompAgentDocument(source, { fileName } = {}) {
+  const frontmatter = splitFrontmatter(source);
+  if (!frontmatter) throw new Error('unsupported agent frontmatter');
+  const name = requiredField(frontmatter.fields, 'name');
+  const description = requiredField(frontmatter.fields, 'description');
+  if (!name || !description || !fileName) throw new Error('unsupported agent frontmatter');
+  const body = frontmatter.body
+    .replaceAll('The Copilot host initializes MCP and supplies its live `tools/list` and schemas in the Chat tools picker.', 'OMP initializes MCP and supplies the live tools and schemas in this session\'s tool inventory.')
+    .replaceAll('from the Chat tools picker', 'from this session\'s tool inventory')
+    .replaceAll('visible in the picker', 'listed in the session\'s tool inventory')
+    .replaceAll('If the Copilot client supports subagents/delegation', 'If the OMP `task` tool is available');
+  // JSON strings are valid YAML double-quoted scalars, so descriptions with
+  // `: ` or `#` cannot break OMP's frontmatter parser.
+  return renderDocument([
+    { key: 'name', value: ompAgentName(fileName) },
+    { key: 'description', value: JSON.stringify(`${name}: ${description}`) }
+  ], `You are the **${name}** SAP agent.
+
+${OMP_HOST_NOTE}
+
+${body.trim()}
+`);
+}
+
 export const HARNESSES = [
   { id: 'github-copilot', label: 'GitHub Copilot', directory: '.copilot', supportsAgents: true, legacyManifest: true },
   { id: 'claude-code', label: 'Claude Code', directory: '.claude', supportsAgents: true, agentFileName: agentMarkdownName, agentDocument: claudeCodeAgentDocument },
@@ -100,7 +130,7 @@ export const HARNESSES = [
   { id: 'gemini-cli', label: 'Gemini CLI', directory: '.gemini', supportsAgents: false },
   { id: 'opencode', label: 'opencode', directory: 'opencode', configHome: true, supportsAgents: true, agentFileName: agentMarkdownName, agentDocument: opencodeAgentDocument },
   { id: 'pi-coding-agent', label: 'Pi Coding Agent', directory: '.pi/agent', supportsAgents: true, agentTargetPrefix: 'prompts', agentFileName: agentMarkdownName, agentDocument: piCodingAgentPromptDocument, root: piCodingAgentRoot },
-  { id: 'omp', label: 'Oh My Pi (OMP)', directory: '.omp/agent', supportsAgents: false, root: ompAgentRoot },
+  { id: 'omp', label: 'Oh My Pi (OMP)', directory: '.omp/agent', supportsAgents: true, agentFileName: agentMarkdownName, agentDocument: ompAgentDocument, root: ompAgentRoot },
   { id: 'cline', label: 'Cline', directory: '.cline', supportsAgents: false },
   { id: 'roo-code', label: 'Roo Code', directory: '.roo', supportsAgents: false },
   { id: 'windsurf', label: 'Windsurf / Devin Desktop', directory: 'devin', supportsAgents: false, root: windsurfSkillsRoot }

package/src/install-user-assets.mjs

@@ -83,7 +83,7 @@ async function planDestinations(harness, files) {
       join('agents', fileName)
     ];
     const aliases = [...new Set(aliasCandidates.filter(alias => alias !== target))];
-    const content = harness.agentDocument ? Buffer.from(harness.agentDocument(raw.toString('utf8')), 'utf8') : raw;
+    const content = harness.agentDocument ? Buffer.from(harness.agentDocument(raw.toString('utf8'), { fileName: sourceName }), 'utf8') : raw;
     destinations.push({ target, content, aliases });
   }
   return destinations;

package/src/integration-common.mjs

@@ -34,27 +34,27 @@ function jsonSafe(value, seen = new WeakSet()) {
   return value;
 }
 
-function jsonText(value) {
+function jsonText(value, { product = 'Integration Suite' } = {}) {
   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).');
+    throw new IntegrationError(`${product} 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.';
+export function toolError(error, { fallback = 'Integration Suite request failed. Check service-key roles and tenant reachability.' } = {}) {
+  let message = fallback;
   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) {
+export async function resultOf(operation, options) {
   try {
-    return { content: [{ type: 'text', text: jsonText(await operation()) }] };
+    return { content: [{ type: 'text', text: jsonText(await operation(), options) }] };
   } catch (error) {
-    return toolError(error);
+    return toolError(error, options);
   }
 }
 

package/src/integration-config.mjs

@@ -53,6 +53,11 @@ function finalize(prefix, source, bindingName, raw) {
   });
 }
 
+/** Validate and freeze raw OAuth client credentials (client-credentials style products). */
+export function finalizeClientCredentials(prefix, source, raw) {
+  return finalize(prefix, source, null, raw);
+}
+
 function explicitConfig(env, prefix) {
   const keys = [`${prefix}_URL`, `${prefix}_TOKEN_URL`, `${prefix}_CLIENT_ID`, `${prefix}_CLIENT_SECRET`];
   if (!keys.some(key => env[key] !== undefined && env[key] !== '')) return null;

package/src/integration-credentials.mjs

@@ -4,17 +4,37 @@
 import { readFileSync } from 'node:fs';
 import { chmod, mkdir, rename, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { OPTIONAL_COMPONENT_KEYS, optionalConfigRecord } from './integration-optional-config.mjs';
 
 const SIDES = ['cpi', 'apim', 'devhub', ...OPTIONAL_COMPONENT_KEYS];
-
-export function integrationCredentialsPath(env = process.env) {
+/** XDG/HOME path of a user-only credential file owned by this toolkit. */
+export function userConfigFilePath(env = process.env, fileName) {
   const configHome = typeof env.XDG_CONFIG_HOME === 'string' && env.XDG_CONFIG_HOME.trim()
     ? env.XDG_CONFIG_HOME.trim()
     : join(env.HOME || env.USERPROFILE || homedir(), '.config');
-  return join(configHome, 'sap-ai-dev-toolkit', 'integration-suite.json');
+  return join(configHome, 'sap-ai-dev-toolkit', fileName);
+}
+
+/** Atomic, user-only (0600) JSON write shared by every credential store. */
+export async function writeUserOnlyJson(path, value) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await chmod(dirname(path), 0o700).catch(() => {});
+  const temporary = join(dirname(path), `.${basename(path, '.json')}.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    await rename(temporary, path);
+  } catch (error) {
+    await rm(temporary, { force: true }).catch(() => {});
+    throw error;
+  }
+  await chmod(path, 0o600).catch(() => {});
+  return path;
+}
+
+export function integrationCredentialsPath(env = process.env) {
+  return userConfigFilePath(env, 'integration-suite.json');
 }
 
 /** Stored keys/normalized optional records; malformed optional records remain isolated by the resolver. */
@@ -56,16 +76,5 @@ export async function storeIntegrationKey(side, config, env = process.env) {
     ...existing,
     [key]: record
   };
-  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-  await chmod(dirname(path), 0o700).catch(() => {});
-  const temporary = join(dirname(path), `.integration-suite.${process.pid}.${randomUUID()}.tmp`);
-  try {
-    await writeFile(temporary, `${JSON.stringify(next, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
-    await rename(temporary, path);
-  } catch (error) {
-    await rm(temporary, { force: true }).catch(() => {});
-    throw error;
-  }
-  await chmod(path, 0o600).catch(() => {});
-  return path;
+  return writeUserOnlyJson(path, next);
 }

package/src/integration-http.mjs

@@ -12,7 +12,11 @@ const SERVER_RETRIES = 2;
 const RETRYABLE_STATUS = new Set([500, 502, 503, 504]);
 // Only idempotent methods are retried; POST (create/deploy/import) is never re-sent.
 const RETRYABLE_METHODS = new Set(['GET', 'PUT']);
-const PAGINATION_HEADERS = new Set(['elements-next-page-token', 'nextpage']);
+// Readable response headers: pagination tokens and counts, and async job locations (never credentials or cookies).
+const READABLE_RESPONSE_HEADERS = new Set(['elements-next-page-token', 'nextpage', 'location', 'x-total-count']);
+// Transport-owned headers a caller can never set or override.
+const RESERVED_REQUEST_HEADERS = new Set(['authorization', 'cookie', 'host', 'content-length', 'content-type', 'accept', 'accept-encoding', 'x-csrf-token', 'connection', 'transfer-encoding']);
+const HEADER_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
 
 export class IntegrationError extends Error {
   constructor(message, evidence = {}) {
@@ -39,7 +43,7 @@ function discard(response) {
   void response.body?.cancel().catch(() => {});
 }
 
-async function readCapped(response, limit, label, signal) {
+export async function readCapped(response, limit, label, signal) {
   const declared = Number(response.headers.get('content-length'));
   if (Number.isFinite(declared) && declared > limit) {
     discard(response);
@@ -340,24 +344,37 @@ function createTransportClient({
     withStatus = false,
     unwrap = true,
     deadline,
-    responseHeaders
+    responseHeaders,
+    headers: extraHeaders
   } = {}) {
     if (deadline !== undefined && !Number.isFinite(deadline)) throw new IntegrationError(`${label} request deadline must be an absolute finite timestamp`);
     if (deadline !== undefined && now() >= deadline) throw timeoutError('request', deadline);
     if (responseHeaders !== undefined && (!Array.isArray(responseHeaders)
-      || responseHeaders.some(name => typeof name !== 'string' || !PAGINATION_HEADERS.has(name.toLowerCase())))) {
-      throw new IntegrationError(`${label} response headers are limited to documented pagination tokens`);
+      || responseHeaders.some(name => typeof name !== 'string' || !READABLE_RESPONSE_HEADERS.has(name.toLowerCase())))) {
+      throw new IntegrationError(`${label} response headers are limited to documented pagination tokens and job locations`);
+    }
+    const callerHeaders = {};
+    for (const [name, value] of Object.entries(extraHeaders || {})) {
+      const normalized = name.toLowerCase();
+      if (!HEADER_NAME.test(normalized) || RESERVED_REQUEST_HEADERS.has(normalized) || normalized.startsWith('proxy-')) {
+        throw new IntegrationError(`${label} request header ${name} is not allowed`);
+      }
+      if (typeof value !== 'string' || /[^\x20-\x7e]/.test(value)) throw new IntegrationError(`${label} request header ${name} has an invalid value`);
+      callerHeaders[normalized] = value;
     }
     const target = new URL(`${url}${path}`);
     for (const [key, value] of Object.entries(query || {})) {
-      if (value !== undefined && value !== null) target.searchParams.set(key, String(value));
+      if (Array.isArray(value)) {
+        // Repeated parameters (`status=A&status=B`) carry OR semantics in SAP REST APIs.
+        for (const item of value) if (item !== undefined && item !== null) target.searchParams.append(key, String(item));
+      } else if (value !== undefined && value !== null) target.searchParams.set(key, String(value));
     }
     // SAP management endpoints require literal OData '$' option names and '%20' spaces.
     // Decode only a leading '$' in parameter names; values stay encoded (including '+' and '&').
     target.search = target.search.replaceAll('+', '%20').replace(/([?&])%24(?=[A-Za-z_])/gi, (_, separator) => `${separator}$`);
     if (target.origin !== origin || target.username || target.password || target.hash) throw new IntegrationError(`${label} request escaped the configured tenant`);
 
-    const baseHeaders = { accept };
+    const baseHeaders = { ...callerHeaders, accept };
     let payload;
     if (json !== undefined) {
       baseHeaders['content-type'] = 'application/json';

package/src/launcher.mjs

@@ -10,7 +10,7 @@ import { adtBaseUrl, adtPort, detectAdtUrl, discoverSapGuiSystems, hasExplicitPo
 import { binaryTarget, cacheDirectory, downloadBinary, findBinary } from './binary.mjs';
 import { MCPProxy } from './mcp-proxy.mjs';
 import { configuredVersionHandoff, installMcpConfig, npxPackageLauncher, repairManagedMcpConfig } from './mcp-config.mjs';
-import { runIntegrationSuiteSetup, runSetup } from './setup.mjs';
+import { runBtpSetup, runCloudAlmSetup, runDatasphereSetup, runIntegrationSuiteSetup, runProcessAutomationSetup, runSetup } from './setup.mjs';
 import { runHarnessSetup } from './harness-setup.mjs';
 import { resolveConfiguredCloudFoundryDestination } from './cf-destination.mjs';
 import { createTlsServerNameAdtProxy } from './tls-adt-proxy.mjs';
@@ -38,7 +38,11 @@ function usage() {
     '  --setup                  Configure generated BAS MCP servers',
     '  --tools                  Also offer full-stack SAP companion MCP servers (use with --setup)',
     '  --setup-integration      Only set up the Integration Suite MCP server: paste CPI/APIM service keys and verify them online',
-    '  --npx                    Launch configured MCP servers through the pinned npm package (use with --setup)',
+    '  --setup-datasphere       Only set up the SAP Datasphere MCP server: sign in with a Datasphere OAuth client and verify it online',
+    '  --setup-process-automation  Only set up the SAP Build Process Automation MCP server: paste a service key, choose technical or user sign-in, verify online',
+    '  --setup-btp              Only set up the SAP BTP platform administration MCP server: locate the btp CLI and check your btp login --sso session',
+    '  --setup-cloud-alm        Only set up the SAP Cloud ALM MCP server: paste the Cloud ALM API service key, verify online',
+    '  --datasphere <command>   Run the bundled SAP Datasphere CLI with a tenant URL and browser temporary code',
     '  --list-destinations      List discovered BAS destinations',
     '  --list-destinations --json  Print redacted JSON status',
     '  --check                  Probe destination availability',
@@ -370,7 +374,16 @@ async function configuredLocalSapGuiDestination(env) {
 }
 
 async function main() {
+  if (args()[0] === '--datasphere') {
+    const { runDatasphereCommand } = await import('./datasphere-command.mjs');
+    process.exitCode = await runDatasphereCommand(args().slice(1), { env: runtimeEnv });
+    return;
+  }
   const setupIntegration = hasFlag('--setup-integration');
+  const setupDatasphere = hasFlag('--setup-datasphere');
+  const setupProcessAutomation = hasFlag('--setup-process-automation');
+  const setupBtp = hasFlag('--setup-btp');
+  const setupCloudAlm = hasFlag('--setup-cloud-alm');
   const setup = hasFlag('--setup');
   const check = hasFlag('--check');
   const list = hasFlag('--list-destinations');
@@ -380,8 +393,7 @@ async function main() {
     process.stdout.write(usage());
     return;
   }
-  if (!setup && !setupIntegration && !check && !list && !doctor && !demo && await handOffToConfiguredVersion()) return;
-  if (doctor && demo) throw new Error('Use either --doctor or --demo, not both.');
+  if (!setup && !setupIntegration && !setupDatasphere && !setupProcessAutomation && !setupBtp && !setupCloudAlm && !check && !list && !doctor && !demo && await handOffToConfiguredVersion()) return;
   if (demo) {
     await runOfflineDemo();
     return;
@@ -419,6 +431,46 @@ async function main() {
     if (!result?.skipped) await runHarnessSetup(result?.servers, { env: runtimeEnv, root });
     return;
   }
+  if (setupDatasphere) {
+    const options = {};
+    if (hasFlag('--npx')) {
+      const launcher = npxPackageLauncher(pkg.version);
+      options.install = (selected, installOptions) => installMcpConfig(selected, { ...installOptions, ...launcher });
+    }
+    const result = await runDatasphereSetup(options);
+    if (!result?.skipped) await runHarnessSetup(result?.servers, { env: runtimeEnv, root });
+    return;
+  }
+  if (setupProcessAutomation) {
+    const options = {};
+    if (hasFlag('--npx')) {
+      const launcher = npxPackageLauncher(pkg.version);
+      options.install = (selected, installOptions) => installMcpConfig(selected, { ...installOptions, ...launcher });
+    }
+    const result = await runProcessAutomationSetup(options);
+    if (!result?.skipped) await runHarnessSetup(result?.servers, { env: runtimeEnv, root });
+    return;
+  }
+  if (setupBtp) {
+    const options = {};
+    if (hasFlag('--npx')) {
+      const launcher = npxPackageLauncher(pkg.version);
+      options.install = (selected, installOptions) => installMcpConfig(selected, { ...installOptions, ...launcher });
+    }
+    const result = await runBtpSetup(options);
+    if (!result?.skipped) await runHarnessSetup(result?.servers, { env: runtimeEnv, root });
+    return;
+  }
+  if (setupCloudAlm) {
+    const options = {};
+    if (hasFlag('--npx')) {
+      const launcher = npxPackageLauncher(pkg.version);
+      options.install = (selected, installOptions) => installMcpConfig(selected, { ...installOptions, ...launcher });
+    }
+    const result = await runCloudAlmSetup(options);
+    if (!result?.skipped) await runHarnessSetup(result?.servers, { env: runtimeEnv, root });
+    return;
+  }
   if (setup) {
     const setupOptions = {
       includeSapDevelopmentToolsPrompt: hasFlag('--tools') || hasFlag('--companion-tools'),

package/src/mcp-config.mjs

@@ -76,6 +76,42 @@ export const SAP_DEVELOPMENT_MCP_SERVERS = Object.freeze([
     bin: 'sap-ai-integration',
     ignoreScripts: true,
     priority: 'optional'
+  }),
+  Object.freeze({
+    id: 'datasphere',
+    name: 'SAP Datasphere',
+    description: 'Full SAP Datasphere suite: spaces, users, roles, database users, connections, modeling objects and packages, task chains, replication flows, Data Marketplace, consumption data and Open SQL, using a Datasphere OAuth client from the host environment or saved with sap-ai-dev --setup-datasphere.',
+    packageName: 'sap-ai-dev-toolkit',
+    bin: 'sap-ai-datasphere',
+    ignoreScripts: true,
+    priority: 'optional'
+  }),
+  Object.freeze({
+    id: 'process-automation',
+    name: 'SAP Build Process Automation',
+    description: 'Inspect process definitions, running, failed and stuck workflow instances, user-task queues and decisions; start processes, send business events, and administer instances and tasks, using a Process Automation service key from the host environment or saved with sap-ai-dev --setup-process-automation.',
+    packageName: 'sap-ai-dev-toolkit',
+    bin: 'sap-ai-process-automation',
+    ignoreScripts: true,
+    priority: 'optional'
+  }),
+  Object.freeze({
+    id: 'sap-btp',
+    name: 'SAP BTP platform administration',
+    description: 'Inspect the global account hierarchy, entitlements and quotas, Service Manager instances and service keys, destinations, identity and destination trust, and Cloud Connectors, and create service instances and keys, through your own btp CLI login (btp login --sso) set up with sap-ai-dev --setup-btp.',
+    packageName: 'sap-ai-dev-toolkit',
+    bin: 'sap-ai-btp',
+    ignoreScripts: true,
+    priority: 'optional'
+  }),
+  Object.freeze({
+    id: 'cloud-alm',
+    name: 'SAP Cloud ALM',
+    description: 'Observe and triage SAP landscapes with SAP Cloud ALM: health, exception and alert hotspots per DEV/TEST/PROD tier, integration and exception monitoring records, monitoring events with CPI message log and SLG1 handoffs, analytics queries, feature and transport deployment status, and confirmation-gated alert closing, using a Cloud ALM API service key from the host environment or saved with sap-ai-dev --setup-cloud-alm.',
+    packageName: 'sap-ai-dev-toolkit',
+    bin: 'sap-ai-cloud-alm',
+    ignoreScripts: true,
+    priority: 'optional'
   })
 ]);
 
@@ -608,7 +644,7 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
   // Values are full npx package specs; a bare version would become --package=<version>.
   const selfSpec = selfVersion ? `sap-ai-dev-toolkit@${selfVersion}` : '';
   const companionVersions = selfSpec
-    ? { 'sap-ai-dev-toolkit': selfSpec, 'hana-cloud-inspector': selfSpec, 'integration-suite': selfSpec }
+    ? { 'sap-ai-dev-toolkit': selfSpec, 'hana-cloud-inspector': selfSpec, 'integration-suite': selfSpec, 'datasphere': selfSpec, 'process-automation': selfSpec, 'sap-btp': selfSpec, 'cloud-alm': selfSpec }
     : {};
   const generated = {
     ...buildMcpEntries(destinations, env),

package/src/process-automation-automation-tools.mjs

@@ -0,0 +1,125 @@
+// SAP Build Process Automation Unified API triggers and automation (iRPA) execution/monitoring tools.
+import { z } from 'zod';
+import { CREATE_ANNOTATIONS, READ_ONLY_ANNOTATIONS, confirmation, requireConfirmation } from './integration-common.mjs';
+import {
+  IRPA_MONITORING, IRPA_RUNTIME, UNIFIED, apiKeyHeaders, enc, environmentId, environmentQuery, guid, identifier,
+  outputFile, payload, timestamp, writeExportFile
+} from './process-automation-common.mjs';
+
+export const AUTOMATION_TOOL_NAMES = Object.freeze([
+  'bpa_list_api_triggers',
+  'bpa_get_api_trigger',
+  'bpa_execute_api_trigger',
+  'bpa_list_automation_triggers',
+  'bpa_get_automation_trigger',
+  'bpa_list_automation_jobs',
+  'bpa_start_automation',
+  'bpa_export_automation_data'
+]);
+
+const EXPORT_PATHS = { bam: '/bam/export', archived_jobs: '/jobs/archived/export' };
+
+export function registerAutomationTools(register, { rest, access }) {
+  const triggerUid = identifier('trigger uid (UUID or projectId.triggerId)');
+  const unified = (method, path, environment, options = {}) => rest.request(method, `${UNIFIED}${path}`, {
+    ...options,
+    query: { ...environmentQuery(access, environment), ...(options.query ?? {}) },
+    headers: apiKeyHeaders(access, 'api-key')
+  });
+  const irpa = (method, path, options = {}) => rest.request(method, `${IRPA_RUNTIME}${path}`, {
+    ...options,
+    headers: apiKeyHeaders(access, 'irpa-api-key', { required: true })
+  });
+
+  register('bpa_list_api_triggers', 'List API triggers',
+    'List process API triggers of an environment via the Unified API (api-key scope trigger_read when using a technical user).',
+    {
+      environment_id: environmentId,
+      filter: z.string().max(1000).optional().describe('OData $filter expression.'),
+      expand: z.string().max(200).optional().describe('OData $expand expression.')
+    },
+    READ_ONLY_ANNOTATIONS,
+    ({ environment_id, filter, expand }) => unified('GET', '/triggers/api', environment_id, {
+      query: { ...(filter ? { $filter: filter } : {}), ...(expand ? { $expand: expand } : {}) }
+    }));
+
+  register('bpa_get_api_trigger', 'Get API trigger',
+    'Get one process API trigger by UUID or projectId.triggerId (environment_id required for the latter; api-key scope trigger_read).',
+    { trigger_uid: triggerUid, environment_id: environmentId },
+    READ_ONLY_ANNOTATIONS,
+    ({ trigger_uid, environment_id }) => unified('GET', `/triggers/api/${enc(trigger_uid)}`, environment_id));
+
+  register('bpa_execute_api_trigger', 'Execute API trigger',
+    'Start a process through its API trigger, or resume a "Wait for an API Call" step by passing execution_id (the process instance id); api-key scope trigger_execute.',
+    {
+      trigger_uid: triggerUid,
+      inputs: payload.default({}),
+      business_key: z.string().max(255).optional(),
+      execution_id: guid.optional().describe('Process instance id waiting in a "Wait for an API Call" step.'),
+      environment_id: environmentId,
+      confirmation
+    },
+    CREATE_ANNOTATIONS,
+    async ({ trigger_uid, inputs, business_key, execution_id, environment_id, confirmation: given }) => {
+      requireConfirmation(given, `EXECUTE BPA TRIGGER ${trigger_uid}`);
+      const { status, data } = await unified('POST', `/triggers/api/${enc(trigger_uid)}`, environment_id, {
+        json: { inputs, ...(business_key ? { businessKey: business_key } : {}), ...(execution_id ? { executionId: execution_id } : {}) },
+        expect: [200, 201, 202, 204],
+        withStatus: true
+      });
+      return { status, data: data ?? null };
+    });
+
+  register('bpa_list_automation_triggers', 'List automation API triggers',
+    'List automation (iRPA) API triggers; requires an environment API key with scope TRIGGER_READ.',
+    {},
+    READ_ONLY_ANNOTATIONS,
+    () => irpa('GET', '/apiTriggers'));
+
+  register('bpa_get_automation_trigger', 'Get automation API trigger',
+    'Get one automation API trigger; requires an environment API key with scope TRIGGER_READ.',
+    { trigger_uid: triggerUid },
+    READ_ONLY_ANNOTATIONS,
+    ({ trigger_uid }) => irpa('GET', `/apiTriggers/${enc(trigger_uid)}`));
+
+  register('bpa_list_automation_jobs', 'List automation jobs',
+    'List jobs (runs) of an automation API trigger, or get one job by job_uid; requires an environment API key with scope TRIGGER_READ.',
+    { trigger_uid: triggerUid, job_uid: identifier('job uid').optional() },
+    READ_ONLY_ANNOTATIONS,
+    ({ trigger_uid, job_uid }) => irpa('GET', job_uid
+      ? `/apiTriggers/${enc(trigger_uid)}/runs/${enc(job_uid)}`
+      : `/apiTriggers/${enc(trigger_uid)}/runs`));
+
+  register('bpa_start_automation', 'Start automation',
+    'Start an automation job through its API trigger; requires an environment API key with scope TRIGGER_EXECUTE.',
+    { trigger_uid: triggerUid, input: payload.default({}), invocation_context: payload.optional(), confirmation },
+    CREATE_ANNOTATIONS,
+    async ({ trigger_uid, input, invocation_context, confirmation: given }) => {
+      requireConfirmation(given, `START BPA AUTOMATION ${trigger_uid}`);
+      return irpa('POST', `/apiTriggers/${enc(trigger_uid)}/runs`, {
+        json: { input, ...(invocation_context ? { invocationContext: invocation_context } : {}) },
+        expect: [201]
+      });
+    });
+
+  register('bpa_export_automation_data', 'Export automation monitoring data',
+    'Export business activity monitoring data (bam, scope BAM_DOWNLOAD) or archived automation jobs (archived_jobs) as CSV; requires an environment API key.',
+    {
+      kind: z.enum(['bam', 'archived_jobs']),
+      from: timestamp.optional(),
+      to: timestamp.optional(),
+      region: z.string().max(64).optional().describe('Language code controlling CSV delimiters.'),
+      output_file: outputFile.optional()
+    },
+    READ_ONLY_ANNOTATIONS,
+    async ({ kind, from, to, region, output_file }) => {
+      const headers = apiKeyHeaders(access, 'irpa-api-key', { required: true });
+      const csv = await rest.request('GET', `${IRPA_MONITORING}${EXPORT_PATHS[kind]}`, {
+        query: Object.fromEntries(Object.entries({ from, to, region }).filter(([, value]) => value !== undefined)),
+        headers,
+        accept: 'text/csv, */*',
+        responseType: 'text'
+      });
+      return output_file ? writeExportFile(output_file, csv) : { csv };
+    });
+}

package/src/process-automation-client.mjs

@@ -0,0 +1,36 @@
+// SAP Build Process Automation REST client, shared by the MCP server and the
+// setup verification. Technical mode: XSUAA client credentials with CSRF and SAP
+// error details. Interactive mode: the signed-in user's bearer token through a
+// static-authorization client (error bodies withheld; messages keep HTTP status).
+import { createDatasphereTokenProvider } from './datasphere-auth.mjs';
+import { createServiceClient, createStaticServiceClient } from './integration-http.mjs';
+import { PROCESS_AUTOMATION_OAUTH } from './process-automation-config.mjs';
+
+export function createProcessAutomationRestClient(config, { env = process.env, fetchImpl, accessToken, persistRefreshToken } = {}) {
+  if (config.auth === 'technical') {
+    return createServiceClient({
+      label: 'PROCESS_AUTOMATION',
+      url: config.url,
+      tokenUrl: config.tokenUrl,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      csrfPath: '/public/workflow/rest/v1/workflow-definitions',
+      env,
+      ...(fetchImpl ? { fetchImpl } : {})
+    });
+  }
+  const provider = createDatasphereTokenProvider({
+    config,
+    env,
+    profile: PROCESS_AUTOMATION_OAUTH,
+    ...(persistRefreshToken ? { persistRefreshToken } : {}),
+    ...(fetchImpl ? { fetchImpl } : {})
+  });
+  return createStaticServiceClient({
+    label: 'PROCESS_AUTOMATION',
+    url: config.url,
+    authorization: async () => `Bearer ${accessToken ?? (await provider.token()).accessToken}`,
+    env,
+    ...(fetchImpl ? { fetchImpl } : {})
+  });
+}