@stackfactor/agent-utils 1.2.16 → 1.2.19

package/dist/esm/serve.js

@@ -14,11 +14,14 @@ const dynamicImport = new Function("specifier", "return import(specifier)");
 // own fetch/SDK calls can cooperate, and we fail the check if it overruns.
 const SELF_CHECK_TIMEOUT_MS = 20_000;
 /**
- * Resolves a repo-relative check-module path within the app root, rejecting any
+ * Resolves a repo-relative agent-module path within the app root, rejecting any
  * path that escapes it or is absolute (the path may originate from the
  * integration config, so treat it as untrusted). Returns null when unsafe.
+ *
+ * Guards both entry points that name a module by configuration: HealthCheck's
+ * `check_code` and Execute's `code` (a webhook's handler module).
  */
-const resolveCheckPath = (rel) => {
+const resolveAgentModulePath = (rel) => {
     const root = process.cwd();
     const dest = resolve(root, rel);
     const back = relative(root, dest);
@@ -27,6 +30,60 @@ const resolveCheckPath = (rel) => {
     }
     return dest;
 };
+/**
+ * Loads the function exported by a repo-relative agent module. Shared by the
+ * self-check (`check_code`) and the webhook entry point (`code`) so both get the
+ * same untrusted-path guard and the same CJS/ESM interop, and neither can drift
+ * into resolving a path the other would reject.
+ *
+ * Never throws: every failure comes back as a `reason` the caller maps to its
+ * own error shape (a CheckResult row, or a gRPC error frame).
+ *
+ * @param rel - Repo-relative module path, e.g. "src/webhooks/inbound-sms.js".
+ * @param namedExport - Preferred named export, tried after `default`/bare export.
+ */
+const loadAgentModule = async (rel, namedExport) => {
+    const modulePath = resolveAgentModulePath(rel);
+    if (!modulePath) {
+        return {
+            reason: "invalid-path",
+            detail: `invalid module path "${rel}"`,
+        };
+    }
+    if (!existsSync(modulePath)) {
+        return {
+            reason: "not-found",
+            detail: `module "${rel}" was not found in the agent image`,
+        };
+    }
+    let exported;
+    try {
+        // Real dynamic import via an indirection the TS compiler won't rewrite. A
+        // literal `import()` is downlevelled to `require()` in the CJS build, and
+        // `require()` cannot resolve a file:// URL ("Cannot find module
+        // 'file:///app/src/check.js'"). `new Function` keeps a genuine `import()` in
+        // both builds; Node resolves the file URL and loads CJS or ESM modules
+        // alike (CJS exports surface as the namespace `default`).
+        const mod = await dynamicImport(pathToFileURL(modulePath).href);
+        exported = mod?.default ?? mod;
+    }
+    catch (error) {
+        return {
+            reason: "load-failed",
+            detail: String(error?.message ?? error),
+        };
+    }
+    const fn = typeof exported === "function"
+        ? exported
+        : exported?.[namedExport] ?? exported?.default;
+    if (typeof fn !== "function") {
+        return {
+            reason: "not-a-function",
+            detail: `module "${rel}" does not export a function`,
+        };
+    }
+    return { fn: fn };
+};
 /** Coerces whatever the agent's check returned into well-formed CheckResult[]. */
 const normalizeChecks = (raw) => {
     if (!Array.isArray(raw)) {
@@ -67,60 +124,41 @@ const runSelfCheck = async (checkCode, config, session) => {
             },
         ];
     }
-    const modulePath = resolveCheckPath(rel);
-    if (!modulePath) {
-        return [
-            {
+    const loaded = await loadAgentModule(rel, "check");
+    if (loaded.reason) {
+        // These rows are the ones this check reported before the loader was factored
+        // out, preserved exactly: a missing or unreachable module is a non-blocking
+        // `warn` (synthetic testing simply isn't available), while a module that IS
+        // there but broken is a blocking `error` — a real defect in a live agent.
+        const rows = {
+            "invalid-path": {
                 name: "synthetic_check",
                 ok: false,
                 detail: `invalid checkCode path "${rel}"`,
                 severity: "warn",
             },
-        ];
-    }
-    if (!existsSync(modulePath)) {
-        return [
-            {
+            "not-found": {
                 name: "synthetic_check",
                 ok: false,
                 detail: `checkCode "${rel}" is configured but the module was not found in the agent image`,
                 severity: "warn",
             },
-        ];
-    }
-    let checkFn;
-    try {
-        // Real dynamic import via an indirection the TS compiler won't rewrite. A
-        // literal `import()` is downlevelled to `require()` in the CJS build, and
-        // `require()` cannot resolve a file:// URL ("Cannot find module
-        // 'file:///app/src/check.js'"). `new Function` keeps a genuine `import()` in
-        // both builds; Node resolves the file URL and loads CJS or ESM check
-        // modules alike (CJS exports surface as the namespace `default`).
-        const mod = await dynamicImport(pathToFileURL(modulePath).href);
-        const exported = mod?.default ?? mod;
-        checkFn =
-            typeof exported === "function" ? exported : exported?.check ?? exported?.default;
-    }
-    catch (error) {
-        return [
-            {
+            "load-failed": {
                 name: "self_check",
                 ok: false,
-                detail: `failed to load check module: ${error?.message ?? error}`,
+                detail: `failed to load check module: ${loaded.detail}`,
                 severity: "error",
             },
-        ];
-    }
-    if (typeof checkFn !== "function") {
-        return [
-            {
+            "not-a-function": {
                 name: "self_check",
                 ok: false,
                 detail: "check module does not export a function",
                 severity: "error",
             },
-        ];
+        };
+        return [rows[loaded.reason]];
     }
+    const checkFn = loaded.fn;
     const abort = new AbortController();
     const timer = setTimeout(() => abort.abort(), SELF_CHECK_TIMEOUT_MS);
     // Bind the same per-request globals main() sees (config, request.session, …)
@@ -321,8 +359,37 @@ export const serve = (main, options = {}) => {
                 signal: abort.signal,
                 session,
             };
+            // Which function actually runs. Default is the agent's own `main` — the
+            // path every caller took before `code` existed, and still the path taken
+            // whenever `code` is empty. A webhook instead names its own handler module
+            // (integration webHooks[].code), so one agent can serve many endpoints
+            // without `main` growing a routing switch. Resolved per request rather
+            // than at boot because the value is per-invocation configuration.
+            let entry = main;
+            const entryPath = String(req.code ?? "").trim();
+            if (entryPath) {
+                const loaded = await loadAgentModule(entryPath, "handler");
+                if (loaded.reason) {
+                    // A named module that will not load is a deployment/config fault, not
+                    // a bad request: the caller cannot fix it and retrying will not help.
+                    // Report it as a result-bearing error frame (not a gRPC status) so the
+                    // receiver gets the reason verbatim and can log which module failed.
+                    logger.log(null, logger.levels.error, `agent Execute could not load entry module "${entryPath}" (${loaded.reason}): ${loaded.detail}`);
+                    if (!abort.signal.aborted) {
+                        call.write({
+                            error: {
+                                code: 500,
+                                message: `entry module "${entryPath}" could not be loaded: ${loaded.detail}`,
+                            },
+                        });
+                    }
+                    call.end();
+                    return;
+                }
+                entry = loaded.fn;
+            }
             try {
-                const result = await runWithContext(context, () => main(abort.signal));
+                const result = await runWithContext(context, () => entry(abort.signal));
                 if (!abort.signal.aborted) {
                     call.write({
                         result: { result_json: JSON.stringify(result ?? null) },

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.2.16",
+  "version": "1.2.19",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -19,7 +19,7 @@
     "work:release": "bash scripts/release.sh",
     "release": "bash scripts/release.sh",
     "release:fanout": "bash scripts/release-fanout.sh",
-    "ar-auth": "npm config set @stackfactor:registry https://us-central1-npm.pkg.dev/virtual-development-team/sf-devenv-npm-private/; TOKEN=$(gcloud auth print-access-token 2>/dev/null || curl -sfH 'Metadata-Flavor: Google' http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token | sed -n 's/.*\"access_token\":\"\\([^\"]*\\)\".*/\\1/p'); test -n \"$TOKEN\" || { echo 'ar-auth: no credential — run: gcloud auth login' >&2; exit 1; }; npm config set //us-central1-npm.pkg.dev/virtual-development-team/:_authToken \"$TOKEN\"; echo 'ar-auth: Artifact Registry scope + token configured'",
+    "ar-auth": "npm config set @stackfactor:registry https://us-central1-npm.pkg.dev/virtual-development-team/sf-devenv-npm-private/; TOKEN=$(gcloud auth print-access-token 2>/dev/null || curl -sfH 'Metadata-Flavor: Google' http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token | sed -n 's/.*\"access_token\":\"\\([^\"]*\\)\".*/\\1/p'); test -n \"$TOKEN\" || { echo 'ar-auth: no credential — run: gcloud auth login' >&2; exit 1; }; npm config set //us-central1-npm.pkg.dev/virtual-development-team/sf-devenv-npm-private/:_authToken \"$TOKEN\"; npm config set //us-central1-npm.pkg.dev/virtual-development-team/:_authToken \"$TOKEN\"; echo 'ar-auth: Artifact Registry scope + token configured'",
     "reinstall": "npm run ar-auth && npm ci"
   },
   "repository": {