nowaikit 4.12.1 → 4.15.0

package/dist/servicenow/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/servicenow/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/servicenow/client.ts"],"names":[],"mappings":"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"}

package/dist/servicenow/client.js

@@ -43,6 +43,30 @@ export function forbiddenDiagnostic(authMethod) {
     return lines.join('\n');
 }
 // ─── Input validation helpers ────────────────────────────────────────────────
+/** Best-effort MIME type from a file extension, for attachments fetched without a content type. */
+function guessContentType(fileName) {
+    const ext = (fileName.split('.').pop() || '').toLowerCase();
+    const map = {
+        pdf: 'application/pdf',
+        doc: 'application/msword',
+        docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+        xls: 'application/vnd.ms-excel',
+        xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        ppt: 'application/vnd.ms-powerpoint',
+        pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+        csv: 'text/csv',
+        txt: 'text/plain',
+        json: 'application/json',
+        xml: 'application/xml',
+        html: 'text/html',
+        png: 'image/png',
+        jpg: 'image/jpeg',
+        jpeg: 'image/jpeg',
+        gif: 'image/gif',
+        zip: 'application/zip',
+    };
+    return map[ext] || 'application/octet-stream';
+}
 /** Validate and sanitize ServiceNow table names (alphanumeric + underscores only) */
 function validateTableName(table) {
     if (!table || !/^[a-zA-Z][a-zA-Z0-9_]*$/.test(table)) {
@@ -91,6 +115,10 @@ export class ServiceNowClient {
     impersonateUserSysId;
     /** For per-user mode: pre-loaded token overrides service-account auth */
     perUserBearerToken;
+    /** Local per-user OAuth only: refresh token + expiry + persist callback (unset for the gateway). */
+    perUserRefreshToken;
+    perUserTokenExpiry;
+    onTokenRefreshed;
     accessToken;
     tokenExpiry;
     constructor(config) {
@@ -104,6 +132,49 @@ export class ServiceNowClient {
         this.requestTimeoutMs = config.requestTimeoutMs || 30000;
         this.impersonateUserSysId = config.impersonateUserSysId;
         this.perUserBearerToken = config.perUserBearerToken;
+        this.perUserRefreshToken = config.perUserRefreshToken;
+        this.perUserTokenExpiry = config.perUserTokenExpiry;
+        this.onTokenRefreshed = config.onTokenRefreshed;
+    }
+    /**
+     * True only for LOCAL per-user OAuth that owns a refresh token + client id (i.e. can renew its
+     * own token). The multi-tenant gateway's per-user mode has no refresh token, so this is false
+     * there and the injected token is used as-is — the gateway path is unchanged.
+     */
+    hasPerUserRefresh() {
+        return this.authMode === 'per-user' && !!this.perUserRefreshToken && !!this.oauthConfig?.clientId;
+    }
+    /** Renew the per-user access token using the stored refresh token (refresh_token grant). */
+    async refreshPerUserToken() {
+        if (!this.perUserRefreshToken || !this.oauthConfig?.clientId) {
+            throw new ServiceNowError('Cannot refresh: no refresh token or OAuth client configured', 'AUTHENTICATION_FAILED');
+        }
+        const body = new URLSearchParams({
+            grant_type: 'refresh_token',
+            client_id: this.oauthConfig.clientId,
+            refresh_token: this.perUserRefreshToken,
+        });
+        // Confidential clients send the secret; public (PKCE) clients omit it.
+        if (this.oauthConfig.clientSecret)
+            body.set('client_secret', this.oauthConfig.clientSecret);
+        const resp = await fetch(`${this.baseUrl}/oauth_token.do`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: body.toString(),
+        });
+        if (!resp.ok) {
+            throw new ServiceNowError(`OAuth token refresh failed: ${resp.status} ${resp.statusText}`, 'AUTHENTICATION_FAILED');
+        }
+        const data = await resp.json();
+        this.perUserBearerToken = data.access_token;
+        if (data.refresh_token)
+            this.perUserRefreshToken = data.refresh_token; // honour rotation
+        const expiresAt = Date.now() + (data.expires_in ? data.expires_in * 1000 * 0.9 : 25 * 60 * 1000);
+        this.perUserTokenExpiry = expiresAt;
+        try {
+            this.onTokenRefreshed?.({ accessToken: this.perUserBearerToken, refreshToken: this.perUserRefreshToken, expiresAt });
+        }
+        catch { /* persistence is best-effort; never fail the request over it */ }
     }
     /**
      * The ServiceNow instance host this client targets (e.g. "acme.service-now.com").
@@ -117,6 +188,56 @@ export class ServiceNowClient {
             return this.baseUrl.toLowerCase();
         }
     }
+    /** Public accessor for the resolved instance base URL (no trailing slash), for building UI links. */
+    get instanceUrl() {
+        return this.baseUrl;
+    }
+    /** Human-facing record URL (opens the form in ServiceNow), not the /api/now REST link. */
+    recordUrl(table, sysId) {
+        return `${this.baseUrl}/${encodeURIComponent(table)}.do?sys_id=${encodeURIComponent(sysId)}`;
+    }
+    /**
+     * Return the fields that ServiceNow Data Policies make mandatory on a table, so an agent can
+     * collect them BEFORE a create/update and avoid the "Data Policy Exception: mandatory fields"
+     * error. Reads sys_data_policy_rule (the mandatory rules) and sys_data_policy2 (the condition
+     * under which each applies). All server-side, read-only.
+     */
+    async getMandatoryFields(table) {
+        const t = validateTableName(table);
+        const rules = await this.queryRecords({
+            table: 'sys_data_policy_rule',
+            query: `table=${t}^mandatory=true`,
+            fields: 'field,sys_data_policy',
+            limit: 100,
+        });
+        const rows = rules.records ?? rules ?? [];
+        // Resolve the parent policy conditions once.
+        const policyIds = Array.from(new Set(rows.map((r) => (typeof r.sys_data_policy === 'object' ? r.sys_data_policy?.value : r.sys_data_policy)).filter(Boolean)));
+        const condByPolicy = new Map();
+        if (policyIds.length) {
+            const pol = await this.queryRecords({
+                table: 'sys_data_policy2',
+                query: `sys_idIN${policyIds.join(',')}`,
+                fields: 'sys_id,short_description,conditions,active',
+                limit: 100,
+            });
+            for (const p of (pol.records ?? pol ?? [])) {
+                condByPolicy.set(p.sys_id, { desc: p.short_description, conditions: p.conditions, active: p.active });
+            }
+        }
+        const fields = rows.map((r) => {
+            const pid = typeof r.sys_data_policy === 'object' ? r.sys_data_policy?.value : r.sys_data_policy;
+            const meta = condByPolicy.get(pid) || {};
+            return { field: r.field, applies_when: meta.conditions || 'always', policy: meta.desc, active: meta.active };
+        }).filter((f) => f.active !== 'false');
+        return {
+            table: t,
+            mandatory_fields: fields,
+            summary: fields.length
+                ? `On ${t}, these fields are made mandatory by data policy: ${fields.map((f) => f.field).join(', ')}. Collect them before creating or updating.`
+                : `No data-policy mandatory fields found on ${t} (dictionary-level mandatory fields may still apply).`,
+        };
+    }
     /**
      * Return a copy of this client configured to run as a specific user.
      * Used for per-request user context switching without mutating the shared client.
@@ -154,6 +275,11 @@ export class ServiceNowClient {
         if (options.bearerToken) {
             copy.authMode = 'per-user';
             copy.perUserBearerToken = options.bearerToken;
+            // A per-request injected token (the gateway path) is not ours to refresh — never carry over
+            // any refresh state from the base client. Keeps hasPerUserRefresh() false for the gateway.
+            copy.perUserRefreshToken = undefined;
+            copy.perUserTokenExpiry = undefined;
+            copy.onTokenRefreshed = undefined;
         }
         return copy;
     }
@@ -164,6 +290,11 @@ export class ServiceNowClient {
         // Per-user mode carries the user's own bearer token (delegated auth) —
         // no service-account token acquisition needed.
         if (this.authMode === 'per-user' && this.perUserBearerToken) {
+            // Local stored-session OAuth: proactively refresh a token that is expired or within 60s of it.
+            // The gateway path has no refresh token (hasPerUserRefresh() === false), so it is untouched.
+            if (this.hasPerUserRefresh() && this.perUserTokenExpiry && Date.now() >= this.perUserTokenExpiry - 60_000) {
+                await this.refreshPerUserToken();
+            }
             return;
         }
         if (this.authMethod === 'basic') {
@@ -308,6 +439,17 @@ export class ServiceNowClient {
                             catch { /* fall through to the throw below */ }
                             continue;
                         }
+                        // Local per-user OAuth that owns a refresh token: renew once and retry. The multi-tenant
+                        // gateway's injected-token per-user mode has NO refresh token, so hasPerUserRefresh() is
+                        // false there and this is skipped — the live Copilot path is unchanged.
+                        if (this.hasPerUserRefresh() && !reauthed) {
+                            reauthed = true;
+                            try {
+                                await this.refreshPerUserToken();
+                            }
+                            catch { /* fall through to the throw below */ }
+                            continue;
+                        }
                         // Attach the actionable checklist so a bare 401 isn't a dead end.
                         if (this.authMethod === 'basic') {
                             errorMessage = `${errorMessage}\n\n${basicAuthDiagnostic()}`;
@@ -375,6 +517,11 @@ export class ServiceNowClient {
         if (params.fields) {
             queryParams.set('sysparm_fields', params.fields);
         }
+        // Return reference fields as readable names, not raw sys_ids. 'all' keeps the sys_id too
+        // (as {display_value, value}) so the agent can still act on the record.
+        if (params.displayValue) {
+            queryParams.set('sysparm_display_value', params.displayValue === 'all' ? 'all' : 'true');
+        }
         if (params.limit !== undefined && params.limit > 0) {
             queryParams.set('sysparm_limit', Math.min(params.limit, 1000).toString());
         }
@@ -465,7 +612,7 @@ export class ServiceNowClient {
     /**
      * Get a single record by sys_id
      */
-    async getRecord(table, sysId, fields) {
+    async getRecord(table, sysId, fields, displayValue) {
         validateTableName(table);
         validateSysId(sysId);
         await this.authenticate();
@@ -473,6 +620,9 @@ export class ServiceNowClient {
         if (fields) {
             queryParams.set('sysparm_fields', fields);
         }
+        if (displayValue) {
+            queryParams.set('sysparm_display_value', displayValue === 'all' ? 'all' : 'true');
+        }
         const url = `${this.baseUrl}/api/now/table/${table}/${sysId}${queryParams.toString() ? '?' + queryParams.toString() : ''}`;
         logger.info(`Getting record from ${table}: ${sysId}`);
         try {
@@ -983,12 +1133,73 @@ export class ServiceNowClient {
      * Accepts base64-encoded content and uploads it as a multipart form.
      */
     async uploadAttachment(table, recordSysId, fileName, contentType, contentBase64) {
+        // Decode base64 to binary, then hand off to the shared binary uploader.
+        const binary = Buffer.from(contentBase64, 'base64');
+        return this.uploadAttachmentBuffer(table, recordSysId, fileName, contentType, binary);
+    }
+    /**
+     * Attach a file to a record by fetching its bytes server-side from a URL, so the file content
+     * never has to travel through the LLM/tool call as a base64 argument. This is the reliable path
+     * for anything larger than a few hundred KB. `sourceHeaders` lets the caller pass auth (e.g. a
+     * bearer/basic credential) for any protected URL. Content type is taken from the caller, then
+     * the response's Content-Type, then guessed from the file extension.
+     */
+    async uploadAttachmentFromUrl(table, recordSysId, fileName, sourceUrl, contentType, sourceHeaders) {
+        const MAX_FETCH_BYTES = 50 * 1024 * 1024; // 50MB safety cap on server-side fetch
+        let src;
+        try {
+            src = new URL(sourceUrl);
+        }
+        catch {
+            throw new ServiceNowError(`source_url is not a valid URL: ${sourceUrl}`, 'INVALID_REQUEST');
+        }
+        if (src.protocol !== 'https:' && src.protocol !== 'http:') {
+            throw new ServiceNowError(`source_url must be http(s), got ${src.protocol}`, 'INVALID_REQUEST');
+        }
+        logger.info(`Fetching attachment "${fileName}" from source URL for ${table}:${recordSysId}`);
+        let fetched;
+        try {
+            fetched = await fetch(src, { headers: sourceHeaders ?? {} });
+        }
+        catch (error) {
+            throw new ServiceNowError(`Failed to fetch source_url: ${error instanceof Error ? error.message : 'Unknown error'}`, 'ATTACHMENT_SOURCE_FETCH_FAILED');
+        }
+        if (!fetched.ok) {
+            throw new ServiceNowError(`source_url returned HTTP ${fetched.status} ${fetched.statusText}`, 'ATTACHMENT_SOURCE_FETCH_FAILED');
+        }
+        const arrayBuf = await fetched.arrayBuffer();
+        const binary = Buffer.from(arrayBuf);
+        if (binary.length > MAX_FETCH_BYTES) {
+            throw new ServiceNowError(`Fetched file is ${(binary.length / 1024 / 1024).toFixed(1)}MB, over the ${MAX_FETCH_BYTES / 1024 / 1024}MB limit`, 'ATTACHMENT_TOO_LARGE');
+        }
+        const responseType = fetched.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() || '';
+        const resolvedType = contentType || responseType || guessContentType(fileName);
+        // Phantom-attachment guard: a protected/expired link (e.g. SharePoint) often returns a tiny
+        // HTML/JSON error page with HTTP 200. Uploading that as "document.pdf" creates an empty, broken
+        // attachment that looks successful. Reject the obvious cases instead of attaching junk.
+        const expectedType = (contentType || guessContentType(fileName)).toLowerCase();
+        const expectsBinary = !expectedType.startsWith('text/') && !/json|xml|csv|html/.test(expectedType);
+        const looksLikeErrorPage = /text\/html|application\/json|application\/xml/.test(responseType);
+        const head = binary.subarray(0, 5).toString('latin1');
+        const magicOk = !expectedType.includes('pdf') ? true : head.startsWith('%PDF'); // PDFs must start with %PDF
+        if (binary.length < 100 && expectsBinary) {
+            throw new ServiceNowError(`source_url returned only ${binary.length} bytes for "${fileName}" — this is almost certainly an error/redirect page, not the file. ` +
+                'The link is likely protected or expired (for SharePoint, use the pre-authorised @microsoft.graph.downloadUrl). Nothing was attached.', 'ATTACHMENT_SOURCE_NOT_A_FILE');
+        }
+        if (expectsBinary && looksLikeErrorPage) {
+            throw new ServiceNowError(`source_url returned ${responseType} but "${fileName}" was expected to be a binary file — this looks like an error page, not the document. Nothing was attached.`, 'ATTACHMENT_SOURCE_NOT_A_FILE');
+        }
+        if (!magicOk) {
+            throw new ServiceNowError(`source_url content is not a valid PDF (missing %PDF header) for "${fileName}". The link likely returned an error page. Nothing was attached.`, 'ATTACHMENT_SOURCE_NOT_A_FILE');
+        }
+        return this.uploadAttachmentBuffer(table, recordSysId, fileName, resolvedType, binary);
+    }
+    /** Shared core: POST raw bytes to ServiceNow's native binary attachment endpoint. */
+    async uploadAttachmentBuffer(table, recordSysId, fileName, contentType, binary) {
         await this.authenticate();
         const url = `${this.baseUrl}/api/now/attachment/file?table_name=${encodeURIComponent(table)}&table_sys_id=${encodeURIComponent(recordSysId)}&file_name=${encodeURIComponent(fileName)}`;
-        logger.info(`Uploading attachment "${fileName}" to ${table}:${recordSysId}`);
+        logger.info(`Uploading attachment "${fileName}" (${binary.length} bytes) to ${table}:${recordSysId}`);
         try {
-            // Decode base64 to binary
-            const binary = Buffer.from(contentBase64, 'base64');
             const response = await fetch(url, {
                 method: 'POST',
                 headers: {
@@ -1023,6 +1234,76 @@ export class ServiceNowClient {
             throw new ServiceNowError(`Failed to upload attachment: ${error instanceof Error ? error.message : 'Unknown error'}`, 'ATTACHMENT_UPLOAD_FAILED');
         }
     }
+    /** Fetch an existing attachment's metadata + raw bytes, server-side (no LLM involvement). */
+    async fetchAttachment(attachmentSysId) {
+        await this.authenticate();
+        const id = validateSysId(attachmentSysId);
+        // Metadata (file_name, content_type, size) via the attachment record.
+        const metaRes = await fetch(`${this.baseUrl}/api/now/attachment/${encodeURIComponent(id)}`, {
+            headers: { Authorization: this.getAuthHeader(), Accept: 'application/json' },
+        });
+        if (!metaRes.ok) {
+            throw new ServiceNowError(metaRes.status === 404 ? `Attachment not found: ${id}` : `HTTP ${metaRes.status}: ${metaRes.statusText}`, metaRes.status === 404 ? 'NOT_FOUND' : 'ATTACHMENT_READ_FAILED');
+        }
+        const meta = (await metaRes.json()).result ?? {};
+        // Raw bytes via the binary file endpoint.
+        const fileRes = await fetch(`${this.baseUrl}/api/now/attachment/${encodeURIComponent(id)}/file`, {
+            headers: { Authorization: this.getAuthHeader() },
+        });
+        if (!fileRes.ok) {
+            throw new ServiceNowError(`HTTP ${fileRes.status}: ${fileRes.statusText}`, 'ATTACHMENT_READ_FAILED');
+        }
+        const bytes = Buffer.from(await fileRes.arrayBuffer());
+        return { meta, bytes };
+    }
+    /**
+     * Copy an existing ServiceNow attachment onto another record, entirely server-side. The bytes
+     * are fetched from the source attachment and re-posted to the target, so nothing passes through
+     * the LLM/tool call. Great for "attach the same document from the RITM onto the KB".
+     */
+    async copyAttachment(attachmentSysId, targetTable, targetRecordSysId, newFileName) {
+        const { meta, bytes } = await this.fetchAttachment(attachmentSysId);
+        const fileName = newFileName || meta.file_name || `attachment-${attachmentSysId}`;
+        const contentType = meta.content_type || guessContentType(fileName);
+        logger.info(`Copying attachment ${attachmentSysId} (${bytes.length} bytes) to ${targetTable}:${targetRecordSysId}`);
+        return this.uploadAttachmentBuffer(targetTable, targetRecordSysId, fileName, contentType, bytes);
+    }
+    /**
+     * Read an existing ServiceNow attachment and return its text content when the file is text-based
+     * (txt/csv/json/xml/html/md). For binary formats (PDF/DOCX/images) it returns metadata plus a note
+     * rather than dumping bytes, since those need a dedicated extractor. All server-side.
+     */
+    async readAttachment(attachmentSysId, maxChars = 200_000) {
+        const { meta, bytes } = await this.fetchAttachment(attachmentSysId);
+        const ct = String(meta.content_type || guessContentType(meta.file_name || '')).toLowerCase();
+        const name = String(meta.file_name || '').toLowerCase();
+        const isTextual = ct.startsWith('text/') ||
+            /json|xml|csv|html|yaml|markdown|javascript|x-www-form-urlencoded/.test(ct) ||
+            /\.(txt|csv|json|xml|html?|md|log|yaml|yml|tsv)$/.test(name);
+        const base = {
+            attachment_sys_id: attachmentSysId,
+            file_name: meta.file_name,
+            content_type: meta.content_type,
+            size_bytes: bytes.length,
+        };
+        if (isTextual) {
+            const text = bytes.toString('utf8');
+            const truncated = text.length > maxChars;
+            return {
+                ...base,
+                text: truncated ? text.slice(0, maxChars) : text,
+                truncated,
+                summary: `Read ${bytes.length} bytes of text from "${meta.file_name}"${truncated ? ` (truncated to ${maxChars} chars)` : ''}`,
+            };
+        }
+        return {
+            ...base,
+            text: null,
+            extractable: false,
+            note: `"${meta.file_name}" is a binary format (${meta.content_type}) that needs a dedicated text extractor. ` +
+                'Use copy_attachment to move it between records, or process the file where it was uploaded.',
+        };
+    }
     /**
      * Execute multiple REST API operations in a single HTTP call (Batch API).
      * Uses /api/now/v1/batch endpoint. Up to 50 operations per batch.
@@ -1085,50 +1366,75 @@ export class ServiceNowClient {
      */
     async executeScript(script, scope) {
         await this.authenticate();
-        logger.info('Executing server-side script');
-        try {
-            // Use the standard script execution endpoint
-            const response = await this.request(`${this.baseUrl}/api/now/v1/batch`, {
+        // ServiceNow has NO supported REST endpoint for running arbitrary background scripts. The only
+        // reliable server-side path is an optional helper the customer installs and reviews: a scoped,
+        // secured Scripted REST API. Point us at it with SCRIPT_EXEC_ENDPOINT (e.g. "/api/x_nowaikit/exec")
+        // and this executes through it; otherwise we fail with a clear, actionable message rather than
+        // silently hitting a non-existent endpoint (the previous implementation targeted a bogus
+        // sys_script_execution table wrapped in a malformed Batch request and never worked).
+        // 1) Optional customer-installed helper (a scoped, secured Scripted REST API) if configured.
+        const endpoint = process.env.SCRIPT_EXEC_ENDPOINT;
+        if (endpoint) {
+            logger.info('Executing server-side script via SCRIPT_EXEC_ENDPOINT');
+            const url = `${this.baseUrl}${endpoint.startsWith('/') ? endpoint : '/' + endpoint}`;
+            const response = await this.request(url, {
                 method: 'POST',
-                body: JSON.stringify({
-                    batch_request_id: `script_${Date.now()}`,
-                    rest_requests: [{
-                            id: 'script_exec',
-                            method: 'POST',
-                            url: '/api/now/table/sys_script_execution',
-                            headers: [
-                                { name: 'Content-Type', value: 'application/json' },
-                                { name: 'Accept', value: 'application/json' },
-                            ],
-                            body: JSON.stringify({
-                                script,
-                                scope: scope || 'global',
-                            }),
-                        }],
-                }),
+                body: JSON.stringify({ script, scope: scope || 'global' }),
+            });
+            return { status: 200, output: (response && response.result !== undefined) ? response.result : response, scope: scope || 'global' };
+        }
+        // 2) Default (no install): run via a one-time, self-terminating scheduled job. ServiceNow has no
+        // REST endpoint to run background scripts, but the SCHEDULER is a separate path — and the job record
+        // is created with the Table API, which works. The wrapper captures the result to a temp property,
+        // then deactivates and deletes the job.
+        return await this.executeViaScheduledJob(script);
+    }
+    async executeViaScheduledJob(script) {
+        const runId = `nwk_${Date.now().toString(36)}_${Math.floor(Math.random() * 1e9).toString(36)}`;
+        const jobName = `NowAIKit exec ${runId}`;
+        const prop = `nowaikit.exec.${runId}`;
+        const wrapper = `var __r, __e = null;\n` +
+            `try { __r = (function(){\n${script}\n})(); } catch (e) { __e = '' + e; }\n` +
+            `try { gs.setProperty(${JSON.stringify(prop)}, JSON.stringify({ ok: __e === null, result: (__r === undefined ? null : __r), error: __e })); } catch (ig) {}\n` +
+            `try { var __j = new GlideRecord('sysauto_script'); if (__j.get('name', ${JSON.stringify(jobName)})) { __j.active = false; __j.deleteRecord(); } } catch (ig) {}\n`;
+        const nowGmt = new Date().toISOString().replace('T', ' ').slice(0, 19);
+        let jobSysId;
+        try {
+            const job = await this.createRecord('sysauto_script', {
+                name: jobName, script: wrapper, active: 'true', run_type: 'once', run_start: nowGmt, next_action: nowGmt,
             });
-            const results = response.serviced_requests || [];
-            if (results.length > 0) {
-                let body;
+            jobSysId = job?.sys_id;
+        }
+        catch (e) {
+            throw new ServiceNowError(`Server-side script execution needs to create a one-time scheduled job (sysauto_script), but that ` +
+                `write was rejected: ${e instanceof Error ? e.message : String(e)}. ` +
+                `Alternatives: use the Table API tools for data changes, run it in ServiceNow (Scripts - Background), ` +
+                `or install the optional script-exec helper and set SCRIPT_EXEC_ENDPOINT.`, 'SCRIPT_EXEC_UNAVAILABLE');
+        }
+        // Poll for the result property (scheduler latency is typically a few to ~60s).
+        const deadline = Date.now() + 90_000;
+        while (Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 3000));
+            const res = await this.queryRecords({ table: 'sys_properties', query: `name=${prop}`, fields: 'sys_id,value', limit: 1 });
+            if (res.count > 0) {
+                const rec = res.records[0];
+                try {
+                    await this.deleteRecord('sys_properties', rec.sys_id);
+                }
+                catch { /* leave it */ }
+                let parsed;
                 try {
-                    body = typeof results[0].body === 'string' ? JSON.parse(results[0].body) : results[0].body;
+                    parsed = JSON.parse(rec.value);
                 }
                 catch {
-                    body = results[0].body;
+                    parsed = { ok: true, result: rec.value };
                 }
-                return {
-                    status: results[0].status_code,
-                    output: body,
-                    scope: scope || 'global',
-                };
+                return { status: 200, ...parsed, via: 'scheduled-job' };
             }
-            return { status: 200, output: 'Script executed (no output captured)', scope: scope || 'global' };
-        }
-        catch (error) {
-            if (error instanceof ServiceNowError)
-                throw error;
-            throw new ServiceNowError(`Script execution failed: ${error instanceof Error ? error.message : 'Unknown error'}`, 'SCRIPT_FAILED');
         }
+        throw new ServiceNowError(`Script was scheduled (sysauto_script "${jobName}"${jobSysId ? ' ' + jobSysId : ''}) but did not report a ` +
+            `result within 90s — the scheduler may be backed up or the script was blocked by instance hardening. ` +
+            `Check the job and its output on the instance.`, 'SCRIPT_EXEC_TIMEOUT');
     }
     /**
      * Natural language update (simplified implementation)