@stackfactor/agent-utils 1.2.18 → 1.2.19

package/dist/cjs/agentProto.d.ts

@@ -6,7 +6,7 @@ import * as grpc from "@grpc/grpc-js";
  * zero or more `Progress` frames (driven by the agent's `onProgress`) followed
  * by exactly one `Result` or `Error`.
  */
-export declare const PROTO = "\nsyntax = \"proto3\";\npackage stackfactor.agent.v1;\n\nservice Agent {\n  rpc Execute(ExecuteRequest) returns (stream Update);\n  // Liveness/health probe served by serve() itself \u2014 no agent code required.\n  // deep=true also exercises the StackFactor auth callback (BACKEND_URL).\n  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);\n}\n\nmessage ExecuteRequest {\n  string content_type = 1;\n  string data_json    = 2;\n  string config_json  = 3;\n  string request_json = 4;\n  int32  event        = 5;\n}\n\nmessage HealthCheckRequest {\n  // Optional JSON carrying { authToken } for the deep backend-callback check.\n  string request_json = 1;\n  bool   deep         = 2;\n  // Deep check only: repo-relative path to the agent's self-check module to run\n  // (e.g. \"src/check.js\"). Empty \u2192 fall back to the conventional \"src/check.js\".\n  string check_code   = 3;\n  // Deep check only: JSON of the resolved agent config (constantsAndVars/\n  // secrets) made available to the self-check as ctx.config. May be empty.\n  string config_json  = 4;\n}\n\n// One result row from the agent's self-check module. The agent owns only its\n// own checks; reachability/ingress/version-drift rows are synthesised backend-\n// side. severity is optional: \"warn\" marks a failing check as non-blocking;\n// empty or \"error\" is blocking.\nmessage CheckResult {\n  string name     = 1;\n  bool   ok       = 2;\n  string detail   = 3;\n  string severity = 4;\n}\n\nmessage HealthCheckResponse {\n  bool   ok                  = 1;\n  bool   backend_reachable   = 2;\n  string version             = 3;\n  string message             = 4;\n  repeated CheckResult checks = 5;\n}\n\nmessage Update {\n  oneof payload {\n    Progress  progress = 1;\n    Result    result   = 2;\n    ErrorInfo error    = 3;\n  }\n}\n\nmessage Progress  { int32 progress = 1; string message = 2; }\nmessage Result    { string result_json = 1; }\nmessage ErrorInfo { int32 code = 1; string message = 2; }\n";
+export declare const PROTO = "\nsyntax = \"proto3\";\npackage stackfactor.agent.v1;\n\nservice Agent {\n  rpc Execute(ExecuteRequest) returns (stream Update);\n  // Liveness/health probe served by serve() itself \u2014 no agent code required.\n  // deep=true also exercises the StackFactor auth callback (BACKEND_URL).\n  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);\n}\n\nmessage ExecuteRequest {\n  string content_type = 1;\n  string data_json    = 2;\n  string config_json  = 3;\n  string request_json = 4;\n  int32  event        = 5;\n  // Optional repo-relative module to run INSTEAD of the agent's main (e.g.\n  // \"src/webhooks/inbound-sms.js\"). Empty -> main, which is every pre-webhook\n  // caller, so this stays wire-compatible with agents built before it existed.\n  // Set by the webhook receiver from the integration's webHooks[].code. Follows\n  // the same untrusted-path rules as HealthCheck's check_code.\n  string code         = 6;\n}\n\nmessage HealthCheckRequest {\n  // Optional JSON carrying { authToken } for the deep backend-callback check.\n  string request_json = 1;\n  bool   deep         = 2;\n  // Deep check only: repo-relative path to the agent's self-check module to run\n  // (e.g. \"src/check.js\"). Empty \u2192 fall back to the conventional \"src/check.js\".\n  string check_code   = 3;\n  // Deep check only: JSON of the resolved agent config (constantsAndVars/\n  // secrets) made available to the self-check as ctx.config. May be empty.\n  string config_json  = 4;\n}\n\n// One result row from the agent's self-check module. The agent owns only its\n// own checks; reachability/ingress/version-drift rows are synthesised backend-\n// side. severity is optional: \"warn\" marks a failing check as non-blocking;\n// empty or \"error\" is blocking.\nmessage CheckResult {\n  string name     = 1;\n  bool   ok       = 2;\n  string detail   = 3;\n  string severity = 4;\n}\n\nmessage HealthCheckResponse {\n  bool   ok                  = 1;\n  bool   backend_reachable   = 2;\n  string version             = 3;\n  string message             = 4;\n  repeated CheckResult checks = 5;\n}\n\nmessage Update {\n  oneof payload {\n    Progress  progress = 1;\n    Result    result   = 2;\n    ErrorInfo error    = 3;\n  }\n}\n\nmessage Progress  { int32 progress = 1; string message = 2; }\nmessage Result    { string result_json = 1; }\nmessage ErrorInfo { int32 code = 1; string message = 2; }\n";
 /**
  * Loads the Agent proto package. proto-loader reads from a file, so the embedded
  * schema is written to a temp path — keeps the package self-contained across the

package/dist/cjs/agentProto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentProto.d.ts","sourceRoot":"","sources":["../../src/agentProto.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AAMtC;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,09DA6DjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAO,GAWnC,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,gBAAgB,QAAO,IAAI,CAAC,iBACc,CAAC"}
+{"version":3,"file":"agentProto.d.ts","sourceRoot":"","sources":["../../src/agentProto.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AAMtC;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,y3EAmEjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAO,GAWnC,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,gBAAgB,QAAO,IAAI,CAAC,iBACc,CAAC"}

package/dist/cjs/agentProto.js

@@ -63,6 +63,12 @@ message ExecuteRequest {
   string config_json  = 3;
   string request_json = 4;
   int32  event        = 5;
+  // Optional repo-relative module to run INSTEAD of the agent's main (e.g.
+  // "src/webhooks/inbound-sms.js"). Empty -> main, which is every pre-webhook
+  // caller, so this stays wire-compatible with agents built before it existed.
+  // Set by the webhook receiver from the integration's webHooks[].code. Follows
+  // the same untrusted-path rules as HealthCheck's check_code.
+  string code         = 6;
 }
 
 message HealthCheckRequest {

package/dist/cjs/client.d.ts

@@ -10,6 +10,13 @@ export interface AgentExecuteRequest {
     config_json: string;
     request_json: string;
     event: number;
+    /**
+     * Optional repo-relative module to run instead of the agent's `main` — the
+     * webhook receiver sets it from the integration's `webHooks[].code`. Omit (or
+     * pass "") for every other caller; the agent then runs `main` exactly as
+     * before. Agents built against an older agent-utils ignore the field.
+     */
+    code?: string;
 }
 export interface CallAgentOptions {
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACrE,gFAAgF;IAChF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA8DD;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GACpB,UAAU,MAAM,EAChB,SAAS,mBAAmB,EAC5B,UAAS,gBAAqB,KAC7B,OAAO,CAAC,GAAG,CA0DV,CAAC;AAEL,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,EAAE,EAAE,OAAO,CAAC;IACZ,gFAAgF;IAChF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GACrB,UAAU,MAAM,EAChB,UAAS,iBAAsB,KAC9B,OAAO,CAAC,WAAW,CA8ClB,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACrE,gFAAgF;IAChF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA8DD;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GACpB,UAAU,MAAM,EAChB,SAAS,mBAAmB,EAC5B,UAAS,gBAAqB,KAC7B,OAAO,CAAC,GAAG,CA0DV,CAAC;AAEL,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,EAAE,EAAE,OAAO,CAAC;IACZ,gFAAgF;IAChF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GACrB,UAAU,MAAM,EAChB,UAAS,iBAAsB,KAC9B,OAAO,CAAC,WAAW,CA8ClB,CAAC"}

package/dist/cjs/serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AA8LtC;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,GAAG,KACT,OAAO,CAAC;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAyHD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAChB,MAAM,SAAS,EACf,UAAS,YAAiB,KACzB,IAAI,CAAC,MA4KP,CAAC"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AA+PtC;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,GAAG,KACT,OAAO,CAAC;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAyHD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAChB,MAAM,SAAS,EACf,UAAS,YAAiB,KACzB,IAAI,CAAC,MA8MP,CAAC"}

package/dist/cjs/serve.js

@@ -53,11 +53,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 = (0, node_path_1.resolve)(root, rel);
     const back = (0, node_path_1.relative)(root, dest);
@@ -66,6 +69,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 (!(0, node_fs_1.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((0, node_url_1.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)) {
@@ -106,60 +163,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 (!(0, node_fs_1.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((0, node_url_1.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, …)
@@ -360,8 +398,37 @@ 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_js_1.default.log(null, logger_js_1.default.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 (0, runtimeContext_js_1.runWithContext)(context, () => main(abort.signal));
+                const result = await (0, runtimeContext_js_1.runWithContext)(context, () => entry(abort.signal));
                 if (!abort.signal.aborted) {
                     call.write({
                         result: { result_json: JSON.stringify(result ?? null) },

package/dist/esm/agentProto.d.ts

@@ -6,7 +6,7 @@ import * as grpc from "@grpc/grpc-js";
  * zero or more `Progress` frames (driven by the agent's `onProgress`) followed
  * by exactly one `Result` or `Error`.
  */
-export declare const PROTO = "\nsyntax = \"proto3\";\npackage stackfactor.agent.v1;\n\nservice Agent {\n  rpc Execute(ExecuteRequest) returns (stream Update);\n  // Liveness/health probe served by serve() itself \u2014 no agent code required.\n  // deep=true also exercises the StackFactor auth callback (BACKEND_URL).\n  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);\n}\n\nmessage ExecuteRequest {\n  string content_type = 1;\n  string data_json    = 2;\n  string config_json  = 3;\n  string request_json = 4;\n  int32  event        = 5;\n}\n\nmessage HealthCheckRequest {\n  // Optional JSON carrying { authToken } for the deep backend-callback check.\n  string request_json = 1;\n  bool   deep         = 2;\n  // Deep check only: repo-relative path to the agent's self-check module to run\n  // (e.g. \"src/check.js\"). Empty \u2192 fall back to the conventional \"src/check.js\".\n  string check_code   = 3;\n  // Deep check only: JSON of the resolved agent config (constantsAndVars/\n  // secrets) made available to the self-check as ctx.config. May be empty.\n  string config_json  = 4;\n}\n\n// One result row from the agent's self-check module. The agent owns only its\n// own checks; reachability/ingress/version-drift rows are synthesised backend-\n// side. severity is optional: \"warn\" marks a failing check as non-blocking;\n// empty or \"error\" is blocking.\nmessage CheckResult {\n  string name     = 1;\n  bool   ok       = 2;\n  string detail   = 3;\n  string severity = 4;\n}\n\nmessage HealthCheckResponse {\n  bool   ok                  = 1;\n  bool   backend_reachable   = 2;\n  string version             = 3;\n  string message             = 4;\n  repeated CheckResult checks = 5;\n}\n\nmessage Update {\n  oneof payload {\n    Progress  progress = 1;\n    Result    result   = 2;\n    ErrorInfo error    = 3;\n  }\n}\n\nmessage Progress  { int32 progress = 1; string message = 2; }\nmessage Result    { string result_json = 1; }\nmessage ErrorInfo { int32 code = 1; string message = 2; }\n";
+export declare const PROTO = "\nsyntax = \"proto3\";\npackage stackfactor.agent.v1;\n\nservice Agent {\n  rpc Execute(ExecuteRequest) returns (stream Update);\n  // Liveness/health probe served by serve() itself \u2014 no agent code required.\n  // deep=true also exercises the StackFactor auth callback (BACKEND_URL).\n  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);\n}\n\nmessage ExecuteRequest {\n  string content_type = 1;\n  string data_json    = 2;\n  string config_json  = 3;\n  string request_json = 4;\n  int32  event        = 5;\n  // Optional repo-relative module to run INSTEAD of the agent's main (e.g.\n  // \"src/webhooks/inbound-sms.js\"). Empty -> main, which is every pre-webhook\n  // caller, so this stays wire-compatible with agents built before it existed.\n  // Set by the webhook receiver from the integration's webHooks[].code. Follows\n  // the same untrusted-path rules as HealthCheck's check_code.\n  string code         = 6;\n}\n\nmessage HealthCheckRequest {\n  // Optional JSON carrying { authToken } for the deep backend-callback check.\n  string request_json = 1;\n  bool   deep         = 2;\n  // Deep check only: repo-relative path to the agent's self-check module to run\n  // (e.g. \"src/check.js\"). Empty \u2192 fall back to the conventional \"src/check.js\".\n  string check_code   = 3;\n  // Deep check only: JSON of the resolved agent config (constantsAndVars/\n  // secrets) made available to the self-check as ctx.config. May be empty.\n  string config_json  = 4;\n}\n\n// One result row from the agent's self-check module. The agent owns only its\n// own checks; reachability/ingress/version-drift rows are synthesised backend-\n// side. severity is optional: \"warn\" marks a failing check as non-blocking;\n// empty or \"error\" is blocking.\nmessage CheckResult {\n  string name     = 1;\n  bool   ok       = 2;\n  string detail   = 3;\n  string severity = 4;\n}\n\nmessage HealthCheckResponse {\n  bool   ok                  = 1;\n  bool   backend_reachable   = 2;\n  string version             = 3;\n  string message             = 4;\n  repeated CheckResult checks = 5;\n}\n\nmessage Update {\n  oneof payload {\n    Progress  progress = 1;\n    Result    result   = 2;\n    ErrorInfo error    = 3;\n  }\n}\n\nmessage Progress  { int32 progress = 1; string message = 2; }\nmessage Result    { string result_json = 1; }\nmessage ErrorInfo { int32 code = 1; string message = 2; }\n";
 /**
  * Loads the Agent proto package. proto-loader reads from a file, so the embedded
  * schema is written to a temp path — keeps the package self-contained across the

package/dist/esm/agentProto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentProto.d.ts","sourceRoot":"","sources":["../../src/agentProto.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AAMtC;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,09DA6DjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAO,GAWnC,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,gBAAgB,QAAO,IAAI,CAAC,iBACc,CAAC"}
+{"version":3,"file":"agentProto.d.ts","sourceRoot":"","sources":["../../src/agentProto.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AAMtC;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,y3EAmEjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAO,GAWnC,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,gBAAgB,QAAO,IAAI,CAAC,iBACc,CAAC"}

package/dist/esm/agentProto.js

@@ -27,6 +27,12 @@ message ExecuteRequest {
   string config_json  = 3;
   string request_json = 4;
   int32  event        = 5;
+  // Optional repo-relative module to run INSTEAD of the agent's main (e.g.
+  // "src/webhooks/inbound-sms.js"). Empty -> main, which is every pre-webhook
+  // caller, so this stays wire-compatible with agents built before it existed.
+  // Set by the webhook receiver from the integration's webHooks[].code. Follows
+  // the same untrusted-path rules as HealthCheck's check_code.
+  string code         = 6;
 }
 
 message HealthCheckRequest {

package/dist/esm/client.d.ts

@@ -10,6 +10,13 @@ export interface AgentExecuteRequest {
     config_json: string;
     request_json: string;
     event: number;
+    /**
+     * Optional repo-relative module to run instead of the agent's `main` — the
+     * webhook receiver sets it from the integration's `webHooks[].code`. Omit (or
+     * pass "") for every other caller; the agent then runs `main` exactly as
+     * before. Agents built against an older agent-utils ignore the field.
+     */
+    code?: string;
 }
 export interface CallAgentOptions {
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACrE,gFAAgF;IAChF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA8DD;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GACpB,UAAU,MAAM,EAChB,SAAS,mBAAmB,EAC5B,UAAS,gBAAqB,KAC7B,OAAO,CAAC,GAAG,CA0DV,CAAC;AAEL,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,EAAE,EAAE,OAAO,CAAC;IACZ,gFAAgF;IAChF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GACrB,UAAU,MAAM,EAChB,UAAS,iBAAsB,KAC9B,OAAO,CAAC,WAAW,CA8ClB,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACrE,gFAAgF;IAChF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA8DD;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GACpB,UAAU,MAAM,EAChB,SAAS,mBAAmB,EAC5B,UAAS,gBAAqB,KAC7B,OAAO,CAAC,GAAG,CA0DV,CAAC;AAEL,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,EAAE,EAAE,OAAO,CAAC;IACZ,gFAAgF;IAChF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GACrB,UAAU,MAAM,EAChB,UAAS,iBAAsB,KAC9B,OAAO,CAAC,WAAW,CA8ClB,CAAC"}

package/dist/esm/serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AA8LtC;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,GAAG,KACT,OAAO,CAAC;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAyHD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAChB,MAAM,SAAS,EACf,UAAS,YAAiB,KACzB,IAAI,CAAC,MA4KP,CAAC"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AA+PtC;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,GAAG,KACT,OAAO,CAAC;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAyHD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAChB,MAAM,SAAS,EACf,UAAS,YAAiB,KACzB,IAAI,CAAC,MA8MP,CAAC"}

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.18",
+  "version": "1.2.19",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",