mcp-for-i 0.1.13 → 0.2.0

package/dist/mcp/modules/objects.js

@@ -0,0 +1,339 @@
+import { checkClCommand, checkResourcePolicy } from "../policy.js";
+import { clampNumber, commandOutcome, enforceWritable, quoteClString, requireDangerousApproval, runClCommand, toolError } from "../tools.js";
+/**
+ * Object and library operations (copy, move, rename, delete, describe).
+ * Every tool changes the IBM i, so each one passes the write gate, checks the
+ * built CL command against the command policy and every library it touches
+ * against the library policy, and reports a failing command as a tool error.
+ */
+/** Object types these tools accept, with the command and keyword that delete each one. */
+export const OBJECT_DELETE_COMMANDS = {
+    "*PGM": { command: "DLTPGM", keyword: "PGM" },
+    "*SRVPGM": { command: "DLTSRVPGM", keyword: "SRVPGM" },
+    "*MODULE": { command: "DLTMOD", keyword: "MODULE" },
+    "*FILE": { command: "DLTF", keyword: "FILE" },
+    "*DTAARA": { command: "DLTDTAARA", keyword: "DTAARA" },
+    "*DTAQ": { command: "DLTDTAQ", keyword: "DTAQ" },
+    "*CMD": { command: "DLTCMD", keyword: "CMD" },
+    "*MSGF": { command: "DLTMSGF", keyword: "MSGF" },
+    "*MENU": { command: "DLTMNU", keyword: "MENU" },
+    "*PNLGRP": { command: "DLTPNLGRP", keyword: "PNLGRP" },
+    "*BNDDIR": { command: "DLTBNDDIR", keyword: "BNDDIR" },
+    "*JOBD": { command: "DLTJOBD", keyword: "JOBD" },
+    "*OUTQ": { command: "DLTOUTQ", keyword: "OUTQ" },
+    "*USRSPC": { command: "DLTUSRSPC", keyword: "USRSPC" },
+    "*USRIDX": { command: "DLTUSRIDX", keyword: "USRIDX" },
+    "*USRQ": { command: "DLTUSRQ", keyword: "USRQ" },
+    "*SQLPKG": { command: "DLTSQLPKG", keyword: "SQLPKG" },
+    "*QRYDFN": { command: "DLTQRY", keyword: "QRY" },
+    "*JRN": { command: "DLTJRN", keyword: "JRN" },
+    "*JRNRCV": { command: "DLTJRNRCV", keyword: "JRNRCV" },
+    "*SBSD": { command: "DLTSBSD", keyword: "SBSD" },
+    "*CLS": { command: "DLTCLS", keyword: "CLS" },
+    "*TBL": { command: "DLTTBL", keyword: "TBL" }
+};
+export const OBJECT_TYPES = Object.keys(OBJECT_DELETE_COMMANDS);
+/** Libraries whose objects these tools never change, move, delete or copy into. */
+const PROTECTED_LIBRARIES = new Set([
+    "QSYS", "QSYS2", "QSYSINC", "QUSRSYS", "QRECOVERY", "QSPL", "QRPLOBJ", "QHLPSYS", "QDOC", "QSRV",
+    "SYSIBM", "SYSIBMADM", "SYSPROC", "SYSTOOLS", "SYSCAT", "SYSFUN", "SYSSTAT"
+]);
+/** True for IBM system libraries whose contents these tools must not change. */
+export function isProtectedLibrary(name) {
+    const upper = String(name || "").toUpperCase();
+    return PROTECTED_LIBRARIES.has(upper) || upper.startsWith("QSYS") || upper.startsWith("#");
+}
+/**
+ * True for library names reserved for the system: the protected libraries
+ * plus every name starting with Q (QGPL, QTEMP, QUSRSYS, ...), which IBM
+ * reserves for its own libraries. Used for deleting or creating whole libraries.
+ */
+export function isReservedLibraryName(name) {
+    const upper = String(name || "").toUpperCase();
+    return isProtectedLibrary(upper) || upper.startsWith("Q");
+}
+const NAME_PATTERN = /^[A-Z#@$][A-Z0-9#@$_.]{0,9}$/;
+/** Validate and uppercase an IBM i object, library, file or member name. */
+export function requireName(value, label) {
+    const name = String(value ?? "").trim().toUpperCase();
+    if (!name)
+        throw new Error(`${label} is required`);
+    if (!NAME_PATTERN.test(name))
+        throw new Error(`Invalid ${label}: ${value}`);
+    return name;
+}
+export function optionalName(value, label, fallback) {
+    return value === undefined || value === null || String(value).trim() === "" ? fallback : requireName(value, label);
+}
+export function requireObjectType(value) {
+    const objectType = String(value ?? "").trim().toUpperCase();
+    if (!objectType)
+        throw new Error("objectType is required");
+    if (!OBJECT_DELETE_COMMANDS[objectType]) {
+        throw new Error(`Unsupported objectType ${value}. Use one of: ${OBJECT_TYPES.join(", ")}`);
+    }
+    return objectType;
+}
+/**
+ * Validate a TEXT value (at most 50 characters, no control characters) and
+ * return it as a CL parameter value: a quoted string, or *BLANK when empty.
+ */
+export function clTextValue(value, label = "text") {
+    if (value === undefined || value === null)
+        throw new Error(`${label} is required`);
+    const text = String(value);
+    if (/[\x00-\x1f\x7f]/.test(text))
+        throw new Error(`Invalid ${label}: control characters are not allowed`);
+    if (text.length > 50)
+        throw new Error(`Invalid ${label}: at most 50 characters (got ${text.length})`);
+    return text.trim() === "" ? "*BLANK" : quoteClString(text);
+}
+export function refuseProtectedLibrary(library, action) {
+    if (isProtectedLibrary(library)) {
+        throw new Error(`Refused: ${action} in system library ${library} is not allowed`);
+    }
+}
+/** Apply the library policy (allowLibraries/denyLibraries) to every library a call touches. */
+export function enforceLibraryPolicy(ctx, toolName, args, libraries) {
+    const policy = ctx.getPolicy(args?.connectionName);
+    for (const library of libraries) {
+        const reason = checkResourcePolicy(policy, toolName, { library });
+        if (reason)
+            throw new Error(`Blocked by policy: ${toolName} (${reason})`);
+    }
+}
+/** Check a built CL command against the command policy, run it, and return the outcome. */
+export async function runCheckedCl(ctx, conn, args, command, timeoutMs = 120000) {
+    const reason = checkClCommand(ctx.getPolicy(args?.connectionName), command);
+    if (reason)
+        throw new Error(`Blocked by policy: ${reason}`);
+    const res = await runClCommand(conn, command, "ile", undefined, timeoutMs);
+    return { ...res, ok: res.code === 0, command };
+}
+const CONNECTION_NAME = { type: "string", description: "Saved IBM i connection name." };
+const APPROVE = { type: "boolean", description: "Set true to approve guarded-policy operations." };
+const OBJECT_TYPE = { type: "string", enum: OBJECT_TYPES, description: "Object type, for example *PGM or *FILE." };
+function annotations(destructive, idempotent = false) {
+    return { readOnlyHint: false, destructiveHint: destructive, idempotentHint: idempotent, openWorldHint: false };
+}
+const tools = [
+    {
+        name: "ibmi.objects.copy",
+        description: "Duplicate an object with CRTDUPOBJ. Copies to toLibrary (default: same library) as newObject (default: same name). data=true also copies file data.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                library: { type: "string" },
+                object: { type: "string" },
+                objectType: OBJECT_TYPE,
+                toLibrary: { type: "string" },
+                newObject: { type: "string" },
+                data: { type: "boolean", description: "Copy the data of a *FILE (DATA(*YES)). Default false." },
+                connectionName: CONNECTION_NAME,
+                approve: APPROVE
+            },
+            required: ["library", "object", "objectType"],
+            additionalProperties: false
+        },
+        annotations: annotations(false)
+    },
+    {
+        name: "ibmi.objects.move",
+        description: "Move an object to another library with MOVOBJ.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                library: { type: "string" },
+                object: { type: "string" },
+                objectType: OBJECT_TYPE,
+                toLibrary: { type: "string" },
+                connectionName: CONNECTION_NAME,
+                approve: APPROVE
+            },
+            required: ["library", "object", "objectType", "toLibrary"],
+            additionalProperties: false
+        },
+        annotations: annotations(true)
+    },
+    {
+        name: "ibmi.objects.rename",
+        description: "Rename an object in its library with RNMOBJ.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                library: { type: "string" },
+                object: { type: "string" },
+                objectType: OBJECT_TYPE,
+                newObject: { type: "string" },
+                connectionName: CONNECTION_NAME,
+                approve: APPROVE
+            },
+            required: ["library", "object", "objectType", "newObject"],
+            additionalProperties: false
+        },
+        annotations: annotations(true)
+    },
+    {
+        name: "ibmi.objects.delete",
+        description: "Delete an object with the delete command for its type (DLTPGM, DLTF, ...). To delete a whole library, " +
+            "set objectType=*LIB, put the library in `library`, and pass approve=true and confirmName equal to the library name. " +
+            "System libraries (Q*, #*, SYS*) are refused.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                library: { type: "string", description: "Library holding the object, or the library to delete when objectType is *LIB." },
+                object: { type: "string", description: "Object name. Not used when objectType is *LIB." },
+                objectType: { type: "string", enum: [...OBJECT_TYPES, "*LIB"] },
+                confirmName: { type: "string", description: "Required for *LIB: repeat the library name exactly." },
+                connectionName: CONNECTION_NAME,
+                approve: APPROVE
+            },
+            required: ["library", "objectType"],
+            additionalProperties: false
+        },
+        annotations: annotations(true)
+    },
+    {
+        name: "ibmi.objects.changeDescription",
+        description: "Change an object's text description with CHGOBJD TEXT(...). An empty text sets *BLANK.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                library: { type: "string" },
+                object: { type: "string" },
+                objectType: OBJECT_TYPE,
+                text: { type: "string", description: "Up to 50 characters." },
+                connectionName: CONNECTION_NAME,
+                approve: APPROVE
+            },
+            required: ["library", "object", "objectType", "text"],
+            additionalProperties: false
+        },
+        annotations: annotations(false, true)
+    },
+    {
+        name: "ibmi.libraries.copy",
+        description: "Copy a library with CPYLIB. createLibrary (default true) creates toLibrary; data (default true) copies file data.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fromLibrary: { type: "string" },
+                toLibrary: { type: "string" },
+                createLibrary: { type: "boolean", description: "CRTLIB(*YES) when true (default), CRTLIB(*NO) to copy into an existing library." },
+                data: { type: "boolean", description: "DATA(*YES) when true (default)." },
+                timeoutMs: { type: "number", description: "How long to wait for CPYLIB (default 600000, max 3600000)." },
+                connectionName: CONNECTION_NAME,
+                approve: APPROVE
+            },
+            required: ["fromLibrary", "toLibrary"],
+            additionalProperties: false
+        },
+        annotations: annotations(false)
+    }
+];
+async function handle(ctx, name, args) {
+    args = args || {};
+    const conn = await ctx.ensureActive(args.connectionName);
+    await enforceWritable(ctx, conn, "qsys.write", args);
+    switch (name) {
+        case "ibmi.objects.copy": {
+            const library = requireName(args.library, "library");
+            const object = requireName(args.object, "object");
+            const objectType = requireObjectType(args.objectType);
+            const toLibrary = optionalName(args.toLibrary, "toLibrary", library);
+            const newObject = optionalName(args.newObject, "newObject", object);
+            if (toLibrary === library && newObject === object) {
+                throw new Error("Copy target is the same as the source: set toLibrary or newObject");
+            }
+            refuseProtectedLibrary(toLibrary, "copying objects");
+            enforceLibraryPolicy(ctx, name, args, [library, toLibrary]);
+            let command = `CRTDUPOBJ OBJ(${object}) FROMLIB(${library}) OBJTYPE(${objectType}) TOLIB(${toLibrary}) NEWOBJ(${newObject})`;
+            if (objectType === "*FILE")
+                command += ` DATA(${args.data ? "*YES" : "*NO"})`;
+            return commandOutcome(await runCheckedCl(ctx, conn, args, command));
+        }
+        case "ibmi.objects.move": {
+            const library = requireName(args.library, "library");
+            const object = requireName(args.object, "object");
+            const objectType = requireObjectType(args.objectType);
+            const toLibrary = requireName(args.toLibrary, "toLibrary");
+            if (toLibrary === library)
+                throw new Error("toLibrary must differ from library");
+            refuseProtectedLibrary(library, "moving objects");
+            refuseProtectedLibrary(toLibrary, "moving objects");
+            enforceLibraryPolicy(ctx, name, args, [library, toLibrary]);
+            const command = `MOVOBJ OBJ(${library}/${object}) OBJTYPE(${objectType}) TOLIB(${toLibrary})`;
+            return commandOutcome(await runCheckedCl(ctx, conn, args, command));
+        }
+        case "ibmi.objects.rename": {
+            const library = requireName(args.library, "library");
+            const object = requireName(args.object, "object");
+            const objectType = requireObjectType(args.objectType);
+            const newObject = requireName(args.newObject, "newObject");
+            if (newObject === object)
+                throw new Error("newObject must differ from object");
+            refuseProtectedLibrary(library, "renaming objects");
+            enforceLibraryPolicy(ctx, name, args, [library]);
+            const command = `RNMOBJ OBJ(${library}/${object}) OBJTYPE(${objectType}) NEWOBJ(${newObject})`;
+            return commandOutcome(await runCheckedCl(ctx, conn, args, command));
+        }
+        case "ibmi.objects.delete": {
+            const objectType = String(args.objectType ?? "").trim().toUpperCase();
+            const library = requireName(args.library, "library");
+            if (objectType === "*LIB") {
+                if (args.object !== undefined && requireName(args.object, "object") !== library) {
+                    throw new Error("For objectType *LIB put the library to delete in `library` and leave `object` out");
+                }
+                if (isReservedLibraryName(library)) {
+                    throw new Error(`Refused: ${library} is a system library and cannot be deleted`);
+                }
+                const guarded = ctx.getPolicy(args?.connectionName).profile === "guarded";
+                if (!guarded && args.approve !== true) {
+                    return toolError(`Deleting library ${library} needs approve=true and confirmName="${library}".`, { library });
+                }
+                if (String(args.confirmName ?? "").trim().toUpperCase() !== library) {
+                    return toolError(`confirmName must repeat the library name exactly (${library}) to delete it.`, { library });
+                }
+                // Under guarded the person confirms this delete on its own, every time.
+                if (guarded)
+                    await requireDangerousApproval(ctx, "qsys.deleteLibrary", args, "");
+                enforceLibraryPolicy(ctx, name, args, [library]);
+                return commandOutcome(await runCheckedCl(ctx, conn, args, `DLTLIB LIB(${library})`, 600000));
+            }
+            const type = requireObjectType(objectType);
+            const object = requireName(args.object, "object");
+            refuseProtectedLibrary(library, "deleting objects");
+            enforceLibraryPolicy(ctx, name, args, [library]);
+            const { command: dlt, keyword } = OBJECT_DELETE_COMMANDS[type];
+            return commandOutcome(await runCheckedCl(ctx, conn, args, `${dlt} ${keyword}(${library}/${object})`));
+        }
+        case "ibmi.objects.changeDescription": {
+            const library = requireName(args.library, "library");
+            const object = requireName(args.object, "object");
+            const objectType = requireObjectType(args.objectType);
+            const text = clTextValue(args.text);
+            refuseProtectedLibrary(library, "changing objects");
+            enforceLibraryPolicy(ctx, name, args, [library]);
+            const command = `CHGOBJD OBJ(${library}/${object}) OBJTYPE(${objectType}) TEXT(${text})`;
+            return commandOutcome(await runCheckedCl(ctx, conn, args, command));
+        }
+        case "ibmi.libraries.copy": {
+            const fromLibrary = requireName(args.fromLibrary, "fromLibrary");
+            const toLibrary = requireName(args.toLibrary, "toLibrary");
+            if (fromLibrary === toLibrary)
+                throw new Error("toLibrary must differ from fromLibrary");
+            if (isReservedLibraryName(toLibrary)) {
+                throw new Error(`Refused: cannot copy into system library ${toLibrary}`);
+            }
+            enforceLibraryPolicy(ctx, name, args, [fromLibrary, toLibrary]);
+            const createLibrary = args.createLibrary === undefined ? true : Boolean(args.createLibrary);
+            const data = args.data === undefined ? true : Boolean(args.data);
+            const timeoutMs = clampNumber(args.timeoutMs, 600000, 1000, 3600000);
+            const command = `CPYLIB FROMLIB(${fromLibrary}) TOLIB(${toLibrary}) CRTLIB(${createLibrary ? "*YES" : "*NO"}) DATA(${data ? "*YES" : "*NO"})`;
+            return commandOutcome(await runCheckedCl(ctx, conn, args, command, timeoutMs));
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}
+export const objectsModule = { tools, handle };

package/dist/mcp/modules/system.js

@@ -0,0 +1,266 @@
+import { clampInteger, json } from "../tools.js";
+const SECTIONS = ["os", "ptfGroups", "authorities", "systemValues", "pase", "tools"];
+/**
+ * System values an agent may read through ibmi.system.info. Kept to values
+ * that describe the system's behaviour; nothing here is a secret.
+ */
+export const SYSTEM_VALUE_ALLOW_LIST = [
+    "QSECURITY", "QPWDLVL", "QALWOBJRST", "QAUDCTL", "QAUDLVL", "QCRTAUT", "QMAXSIGN", "QINACTITV",
+    "QCCSID", "QCHRID", "QLANGID", "QCNTRYID", "QKBDTYPE", "QCURSYM",
+    "QDATFMT", "QDATSEP", "QTIMSEP", "QDECFMT", "QTIMZON", "QUTCOFFSET", "QLEAPADJ",
+    "QSYSLIBL", "QUSRLIBL", "QMODEL", "QPRCFEAT", "QSRLNBR", "QIPLTYPE", "QAUTOVRT", "QJOBMSGQFL"
+];
+/** Helper tools looked up in PASE: on PATH first, then in the IBM i open source location. */
+const HELPER_TOOLS = ["pfgrep", "openssl", "git", "bash", "python3", "node", "java"];
+const PASE_ENV_VARS = ["PATH", "HOME", "SHELL", "LANG", "LC_ALL", "TZ", "QIBM_CCSID", "QIBM_PASE_CCSID"];
+const MAPEPIRE_PATHS = [
+    "/QOpenSys/pkgs/bin/mapepire",
+    "/QOpenSys/pkgs/lib/mapepire/mapepire-server.jar",
+    "/opt/mapepire/bin/mapepire"
+];
+const PTF_GROUP_DEFAULT_LIMIT = 100;
+const PTF_GROUP_MAX_LIMIT = 1000;
+/** The single PASE script used for the `pase` and `tools` sections. It takes no user input. */
+export function buildPaseProbeScript() {
+    return [
+        `printf 'uname=%s\\n' "$(uname -srv 2>/dev/null)"`,
+        ...PASE_ENV_VARS.map(name => `printf 'env.${name}=%s\\n' "\${${name}:-}"`),
+        `for t in ${HELPER_TOOLS.join(" ")}; do ` +
+            `p=$(command -v "$t" 2>/dev/null); ` +
+            `if [ -z "$p" ] && [ -x "/QOpenSys/pkgs/bin/$t" ]; then p="/QOpenSys/pkgs/bin/$t"; fi; ` +
+            `printf 'tool.%s=%s\\n' "$t" "$p"; done`,
+        `m=$(command -v mapepire 2>/dev/null); ` +
+            `if [ -z "$m" ]; then for c in ${MAPEPIRE_PATHS.join(" ")}; do if [ -e "$c" ]; then m="$c"; break; fi; done; fi; ` +
+            `printf 'tool.mapepire-server=%s\\n' "$m"`
+    ].join("; ");
+}
+export function parsePaseProbe(stdout) {
+    const env = {};
+    const tools = {};
+    let uname = null;
+    for (const line of String(stdout || "").split(/\r?\n/)) {
+        const separator = line.indexOf("=");
+        if (separator <= 0)
+            continue;
+        const key = line.slice(0, separator);
+        const value = line.slice(separator + 1).trim();
+        if (key === "uname")
+            uname = value || null;
+        else if (key.startsWith("env."))
+            env[key.slice(4)] = value || null;
+        else if (key.startsWith("tool."))
+            tools[key.slice(5)] = value || null;
+    }
+    return { uname, env, tools };
+}
+function sqlList(values) {
+    // Values come from the fixed allow-list above, never from the caller.
+    return values.map(value => `'${value.replace(/'/g, "''")}'`).join(", ");
+}
+function text(value) {
+    if (value === null || value === undefined)
+        return null;
+    const str = String(value).trim();
+    return str === "" || str === "-" ? null : str;
+}
+function num(value) {
+    if (value === null || value === undefined || value === "" || value === "-")
+        return null;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+async function osSection(conn) {
+    const rows = await conn.runSQL("select OS_NAME, OS_VERSION, OS_RELEASE, HOST_NAME, TOTAL_CPUS, CONFIGURED_CPUS, TOTAL_MEMORY " +
+        "from SYSIBMADM.ENV_SYS_INFO fetch first 1 row only");
+    const row = rows[0] || {};
+    const version = String(row.OS_VERSION ?? "").replace(/\D/g, "");
+    const release = String(row.OS_RELEASE ?? "").replace(/\D/g, "");
+    const out = {
+        osName: text(row.OS_NAME),
+        release: version && release ? `${Number(version)}.${Number(release)}` : null,
+        hostName: text(row.HOST_NAME),
+        totalCpus: num(row.TOTAL_CPUS),
+        configuredCpus: num(row.CONFIGURED_CPUS),
+        totalMemoryMb: num(row.TOTAL_MEMORY)
+    };
+    try {
+        const status = await conn.runSQL("select PARTITION_ID, MAIN_STORAGE_SIZE, SYSTEM_ASP_STORAGE, SYSTEM_ASP_USED, TOTAL_JOBS_IN_SYSTEM, ELAPSED_CPU_USED " +
+            "from QSYS2.SYSTEM_STATUS_INFO fetch first 1 row only");
+        const s = status[0] || {};
+        out.status = {
+            partitionId: num(s.PARTITION_ID),
+            mainStorageKb: num(s.MAIN_STORAGE_SIZE),
+            systemAspStorageMb: num(s.SYSTEM_ASP_STORAGE),
+            systemAspUsedPercent: num(s.SYSTEM_ASP_USED),
+            totalJobs: num(s.TOTAL_JOBS_IN_SYSTEM),
+            elapsedCpuUsedPercent: num(s.ELAPSED_CPU_USED)
+        };
+    }
+    catch (error) {
+        out.statusError = error?.message || String(error);
+    }
+    return out;
+}
+async function ptfGroupsSection(conn, limit) {
+    // One row per group: the newest level known and the newest level installed.
+    const rows = await conn.runSQL("with L as (select PTF_GROUP_NAME, max(PTF_GROUP_DESCRIPTION) as DESCRIPTION, " +
+        "max(PTF_GROUP_LEVEL) as LATEST_LEVEL, " +
+        "max(case when PTF_GROUP_STATUS = 'INSTALLED' then PTF_GROUP_LEVEL end) as INSTALLED_LEVEL " +
+        "from QSYS2.GROUP_PTF_INFO group by PTF_GROUP_NAME) " +
+        "select L.PTF_GROUP_NAME, L.DESCRIPTION, L.LATEST_LEVEL, L.INSTALLED_LEVEL, " +
+        "(select max(G.PTF_GROUP_STATUS) from QSYS2.GROUP_PTF_INFO G where G.PTF_GROUP_NAME = L.PTF_GROUP_NAME " +
+        "and G.PTF_GROUP_LEVEL = L.LATEST_LEVEL) as LATEST_STATUS " +
+        `from L order by L.PTF_GROUP_NAME fetch first ${limit + 1} rows only`);
+    const truncated = rows.length > limit;
+    return {
+        groups: rows.slice(0, limit).map((row) => ({
+            group: text(row.PTF_GROUP_NAME),
+            description: text(row.DESCRIPTION),
+            latestLevel: num(row.LATEST_LEVEL),
+            latestStatus: text(row.LATEST_STATUS),
+            installedLevel: num(row.INSTALLED_LEVEL)
+        })),
+        returned: Math.min(rows.length, limit),
+        truncated,
+        ...(truncated ? { truncatedReason: `More than ${limit} PTF groups; raise ptfGroupLimit (max ${PTF_GROUP_MAX_LIMIT}).` } : {})
+    };
+}
+async function authoritiesSection(conn) {
+    const rows = await conn.runSQL("select USER as RUNTIME_USER, SYSTEM_USER as SYSTEM_USER_NAME, U.USER_CLASS_NAME, U.SPECIAL_AUTHORITIES, " +
+        "U.GROUP_PROFILE_NAME, U.SUPPLEMENTAL_GROUP_LIST, U.LIMIT_CAPABILITIES, U.STATUS " +
+        "from QSYS2.USER_INFO U where U.AUTHORIZATION_NAME = USER fetch first 1 row only");
+    const row = rows[0];
+    if (!row)
+        return { user: null, specialAuthorities: [], note: "No QSYS2.USER_INFO row for the current user." };
+    const split = (value) => String(value ?? "").split(/\s+/).map(item => item.trim()).filter(item => item && item !== "*NONE" && item !== "-");
+    return {
+        user: text(row.RUNTIME_USER),
+        systemUser: text(row.SYSTEM_USER_NAME),
+        userClass: text(row.USER_CLASS_NAME),
+        specialAuthorities: split(row.SPECIAL_AUTHORITIES),
+        groupProfile: text(row.GROUP_PROFILE_NAME),
+        supplementalGroups: split(row.SUPPLEMENTAL_GROUP_LIST),
+        limitCapabilities: text(row.LIMIT_CAPABILITIES),
+        status: text(row.STATUS)
+    };
+}
+async function systemValuesSection(conn, names) {
+    const rows = await conn.runSQL("select SYSTEM_VALUE_NAME, CURRENT_NUMERIC_VALUE, CURRENT_CHARACTER_VALUE from QSYS2.SYSTEM_VALUE_INFO " +
+        `where SYSTEM_VALUE_NAME in (${sqlList(names)}) order by SYSTEM_VALUE_NAME`);
+    const values = {};
+    for (const row of rows) {
+        const name = text(row.SYSTEM_VALUE_NAME);
+        if (!name)
+            continue;
+        const character = text(row.CURRENT_CHARACTER_VALUE);
+        values[name] = character !== null ? character : num(row.CURRENT_NUMERIC_VALUE);
+    }
+    const missing = names.filter(name => !(name in values));
+    return { values, ...(missing.length ? { notReturned: missing } : {}) };
+}
+function resolveSections(value) {
+    if (value === undefined || value === null)
+        return [...SECTIONS];
+    if (!Array.isArray(value) || value.length === 0)
+        throw new Error("sections must be a non-empty array");
+    const out = [];
+    for (const item of value) {
+        const name = String(item);
+        if (!SECTIONS.includes(name))
+            throw new Error(`Unknown section: ${item}. Use ${SECTIONS.join(", ")}`);
+        if (!out.includes(name))
+            out.push(name);
+    }
+    return out;
+}
+function resolveSystemValues(value) {
+    if (value === undefined || value === null)
+        return [...SYSTEM_VALUE_ALLOW_LIST];
+    if (!Array.isArray(value) || value.length === 0)
+        throw new Error("systemValues must be a non-empty array");
+    const names = value.map(item => String(item).trim().toUpperCase());
+    const blocked = names.filter(name => !SYSTEM_VALUE_ALLOW_LIST.includes(name));
+    if (blocked.length) {
+        throw new Error(`System value(s) not in the allow-list: ${blocked.join(", ")}. Allowed: ${SYSTEM_VALUE_ALLOW_LIST.join(", ")}`);
+    }
+    return [...new Set(names)];
+}
+async function systemInfo(ctx, args) {
+    const sections = resolveSections(args?.sections);
+    const systemValues = resolveSystemValues(args?.systemValues);
+    const ptfGroupLimit = clampInteger(args?.ptfGroupLimit, 1, PTF_GROUP_MAX_LIMIT, PTF_GROUP_DEFAULT_LIMIT);
+    const conn = await ctx.ensureActive(args?.connectionName);
+    const output = { sections };
+    const errors = {};
+    const run = async (section, loader) => {
+        if (!sections.includes(section))
+            return;
+        try {
+            output[section] = await loader();
+        }
+        catch (error) {
+            errors[section] = error?.message || String(error);
+        }
+    };
+    await run("os", () => osSection(conn));
+    await run("ptfGroups", () => ptfGroupsSection(conn, ptfGroupLimit));
+    await run("authorities", () => authoritiesSection(conn));
+    await run("systemValues", () => systemValuesSection(conn, systemValues));
+    if (sections.includes("pase") || sections.includes("tools")) {
+        try {
+            const res = await conn.sendCommand({ command: buildPaseProbeScript() });
+            if (!res || (res.code !== 0 && !String(res.stdout || "").trim())) {
+                throw new Error(`PASE probe failed (exit ${res?.code ?? "unknown"})${res?.stderr ? `: ${String(res.stderr).trim()}` : ""}`);
+            }
+            const probe = parsePaseProbe(res.stdout);
+            if (sections.includes("pase"))
+                output.pase = { uname: probe.uname, env: probe.env };
+            if (sections.includes("tools"))
+                output.tools = probe.tools;
+        }
+        catch (error) {
+            const message = error?.message || String(error);
+            if (sections.includes("pase"))
+                errors.pase = message;
+            if (sections.includes("tools"))
+                errors.tools = message;
+        }
+    }
+    if (Object.keys(errors).length)
+        output.errors = errors;
+    return json(output);
+}
+export const systemModule = {
+    tools: [
+        {
+            name: "ibmi.system.info",
+            description: "Read-only summary of the IBM i system: OS release, PTF group levels, the current user's special authorities, " +
+                "selected system values, PASE environment and which helper tools (pfgrep, openssl, git, bash, python3, node, java, " +
+                "mapepire-server) are installed. Use sections to pick parts; a failing section is reported under errors.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    connectionName: { type: "string", description: "Saved IBM i connection name." },
+                    sections: {
+                        type: "array",
+                        items: { type: "string", enum: [...SECTIONS] },
+                        description: "Sections to return (default: all)."
+                    },
+                    systemValues: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: `System values to read (default: all allowed). Allowed: ${SYSTEM_VALUE_ALLOW_LIST.join(", ")}.`
+                    },
+                    ptfGroupLimit: { type: "number", description: `Maximum PTF groups returned (default ${PTF_GROUP_DEFAULT_LIMIT}, max ${PTF_GROUP_MAX_LIMIT}).` }
+                },
+                additionalProperties: false
+            },
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+        }
+    ],
+    handle: async (ctx, name, args) => {
+        if (name === "ibmi.system.info")
+            return systemInfo(ctx, args);
+        throw new Error(`Unknown tool: ${name}`);
+    }
+};