@stackfactor/agent-utils 1.2.16 → 1.2.19

package/dist/cjs/langChain.js

@@ -608,6 +608,234 @@ const resolveTemperatureSetting = (modelName, config) => {
     }
     return { temperature: clamped };
 };
+/**
+ * Whether a Claude model can run web search through dynamic filtering, where
+ * Claude writes and runs code that filters the search results before they reach
+ * the context window instead of loading every result into it. Requires Claude
+ * 4.6 or later (the models with programmatic tool calling); on anything earlier
+ * the filtering tool versions return a 400 unless search is pinned to
+ * `allowed_callers: ["direct"]`.
+ * @param modelName - The Claude model identifier being routed
+ * @returns `true` when the model supports dynamic filtering
+ */
+const supportsAnthropicDynamicFiltering = (modelName) => /^claude-(opus|sonnet|haiku)-4-(?:[6-9]|\d\d)\b/.test(modelName) ||
+    /^claude-(opus|sonnet|haiku|fable|mythos)-(?:[5-9]|\d\d)\b/.test(modelName);
+/**
+ * Normalizes `config.webSearch` into an options object, returning `null` when
+ * web search is off so callers can use it as the single enablement gate.
+ */
+const getWebSearchOptions = (config) => {
+    const webSearch = config?.webSearch;
+    if (!webSearch)
+        return null;
+    return webSearch === true ? {} : webSearch;
+};
+/**
+ * Builds the provider-native web search tool definition for a model:
+ *  - `claude-` → Anthropic's `web_search` server tool, executed by the Messages
+ *    API within a single request and answered with citations. Defaults to the
+ *    dynamic-filtering tool version on models that support it, so search results
+ *    are filtered by code before they reach the context window.
+ *  - `gpt-` → OpenAI's hosted `web_search` tool (Responses API). Context spend
+ *    is governed by `search_context_size` (OpenAI defaults to `medium`).
+ *  - `gemini-` → Google's `googleSearch` grounding tool. Google exposes no
+ *    result-filtering or context-size control; leaving `searchTypes` unset keeps
+ *    grounding on text-only web results rather than image bytes.
+ * Returns `null` for providers with no native web search (DeepSeek, Kimi, GLM),
+ * warning instead of throwing so one config can be pointed at any model.
+ * @param modelName - The model identifier being routed
+ * @param options - Normalized options from `getWebSearchOptions`
+ * @returns The provider's tool definition, or `null` when unsupported
+ */
+const buildWebSearchTool = (modelName, options) => {
+    const { allowedDomains, blockedDomains, userLocation } = options;
+    if (modelName.startsWith("claude-")) {
+        // The API returns a 400 when both filters are present, so fail locally
+        // rather than paying for the round trip.
+        if (allowedDomains && blockedDomains) {
+            throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.BAD_REQUEST, "Anthropic web search accepts allowedDomains or blockedDomains, not both.");
+        }
+        // Prefer the newest tool version the model can actually run. Basic search
+        // loads every result into the context window; from `web_search_20260209`
+        // Claude filters them with code first, and `web_search_20260318` can also
+        // keep the consumed results out of the response.
+        const canFilter = supportsAnthropicDynamicFiltering(modelName);
+        const type = options.toolVersion ||
+            (canFilter ? "web_search_20260318" : "web_search_20250305");
+        const version = Number(type.slice(-8));
+        // Filtering versions default to running search from inside code execution.
+        // Say so explicitly when it is not wanted (or not possible), which is what
+        // the API requires from models without programmatic tool calling.
+        const directOnly = version >= 20260209 && (options.dynamicFiltering === false || !canFilter);
+        return {
+            type,
+            name: "web_search",
+            ...(options.maxUses ? { max_uses: options.maxUses } : {}),
+            ...(allowedDomains ? { allowed_domains: allowedDomains } : {}),
+            ...(blockedDomains ? { blocked_domains: blockedDomains } : {}),
+            ...(userLocation
+                ? { user_location: { type: "approximate", ...userLocation } }
+                : {}),
+            ...(directOnly ? { allowed_callers: ["direct"] } : {}),
+            ...(version >= 20260318
+                ? { response_inclusion: options.responseInclusion || "excluded" }
+                : {}),
+        };
+    }
+    if (modelName.startsWith("gpt-")) {
+        return {
+            type: "web_search",
+            ...(allowedDomains
+                ? { filters: { allowed_domains: allowedDomains } }
+                : {}),
+            ...(userLocation
+                ? { user_location: { type: "approximate", ...userLocation } }
+                : {}),
+            ...(options.searchContextSize
+                ? { search_context_size: options.searchContextSize }
+                : {}),
+        };
+    }
+    if (modelName.startsWith("gemini-")) {
+        // `timeRangeFilter` is the only filter the Gemini API exposes;
+        // `excludeDomains` is a Vertex AI field and is rejected here, so domain
+        // filters are deliberately not mapped for Google.
+        return {
+            googleSearch: options.timeRange
+                ? { timeRangeFilter: options.timeRange }
+                : {},
+        };
+    }
+    logger_js_1.default.log(null, logger_js_1.default.levels.warn, `Model "${modelName}" has no native web search tool; ignoring the configured webSearch options.`);
+    return null;
+};
+/**
+ * Flattens LangChain message content into plain text. Content is a string for
+ * ordinary completions, but every provider switches to an array of blocks once
+ * a server-side tool runs — Anthropic interleaves `server_tool_use` and
+ * `web_search_tool_result` blocks with the answer text, and OpenAI's Responses
+ * API returns annotated text blocks — so without this the JSON parse pipeline
+ * would receive a non-string and every web-search call would fail.
+ * @param content - A message's `content` field, or a raw string
+ * @returns The concatenated text of all text blocks
+ */
+const extractTextContent = (content) => {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    let text = "";
+    for (const block of content) {
+        if (typeof block === "string")
+            text += block;
+        else if (block?.type === "text" && typeof block.text === "string") {
+            text += block.text;
+        }
+    }
+    return text;
+};
+const createWebSearchUsage = () => ({
+    reportedRequests: 0,
+    callIds: new Set(),
+    grounded: false,
+    sources: new Map(),
+});
+/**
+ * Folds one message — or one streaming chunk — into a `WebSearchUsage`. Safe to
+ * call on every chunk of a stream and on messages that involved no search.
+ */
+const collectWebSearchUsage = (payload, usage) => {
+    if (!payload)
+        return;
+    const addSource = (url, title) => {
+        if (typeof url === "string" && url && !usage.sources.has(url)) {
+            usage.sources.set(url, {
+                url,
+                ...(typeof title === "string" ? { title } : {}),
+            });
+        }
+    };
+    if (Array.isArray(payload.content)) {
+        for (const block of payload.content) {
+            if (!block || typeof block !== "object")
+                continue;
+            // Anthropic: results of a search the API executed server-side.
+            if (block.type === "web_search_tool_result" &&
+                Array.isArray(block.content)) {
+                for (const result of block.content) {
+                    addSource(result?.url, result?.title);
+                }
+            }
+            // Anthropic: citations attached to the answer's text blocks.
+            if (Array.isArray(block.citations)) {
+                for (const citation of block.citations) {
+                    addSource(citation?.url, citation?.title);
+                }
+            }
+            // OpenAI Responses API: one block per executed search, plus url citations.
+            if (block.type === "web_search_call" && block.id) {
+                usage.callIds.add(block.id);
+            }
+            if (Array.isArray(block.annotations)) {
+                for (const annotation of block.annotations) {
+                    if (annotation?.type === "url_citation") {
+                        addSource(annotation.url, annotation.title);
+                    }
+                }
+            }
+        }
+    }
+    const metadata = payload.response_metadata;
+    if (!metadata)
+        return;
+    const requests = metadata.usage?.server_tool_use?.web_search_requests;
+    if (typeof requests === "number" && requests > usage.reportedRequests) {
+        usage.reportedRequests = requests;
+    }
+    const grounding = metadata.groundingMetadata;
+    if (grounding) {
+        usage.grounded = true;
+        for (const chunk of grounding.groundingChunks || []) {
+            addSource(chunk?.web?.uri, chunk?.web?.title);
+        }
+    }
+};
+/**
+ * Adds a call's web-search usage to the caller-supplied tracker. Searches are
+ * billed per request rather than per token (Anthropic charges $10 per 1,000
+ * searches; Google charges per grounded request), so the rate is read from the
+ * `<model>-web-search-costs` constant expressed in USD per 1,000 searches and
+ * accumulated under `<model>_webSearches`. Sources are appended to
+ * `tracker.webSearchSources`, deduplicated by URL across the whole run.
+ */
+const updateWebSearchUsageTracker = (tracker, modelName, usage, config) => {
+    if (!tracker || !modelName)
+        return;
+    // The three signals describe the same searches from different providers, so
+    // the largest one is the count rather than their sum.
+    const searches = Math.max(usage.reportedRequests, usage.callIds.size, usage.grounded ? 1 : 0);
+    if (!searches && usage.sources.size === 0)
+        return;
+    if (typeof tracker.cost !== "number")
+        tracker.cost = 0;
+    if (!tracker.tokens || typeof tracker.tokens !== "object")
+        tracker.tokens = {};
+    if (searches > 0) {
+        const addedCost = (searches / 1_000) * getModelRate(modelName, config, "web-search");
+        if (Number.isFinite(addedCost) && addedCost > 0)
+            tracker.cost += addedCost;
+        const key = `${modelName}_webSearches`;
+        tracker.tokens[key] = (tracker.tokens[key] || 0) + searches;
+    }
+    if (usage.sources.size > 0) {
+        const sources = tracker.webSearchSources || (tracker.webSearchSources = []);
+        for (const source of usage.sources.values()) {
+            if (!sources.some((existing) => existing.url === source.url)) {
+                sources.push(source);
+            }
+        }
+    }
+};
 /**
  * Instantiates and returns the appropriate LangChain chat model based on the model
  * name prefix. `claude-` maps to `ChatAnthropic`, `gemini-` maps to
@@ -634,6 +862,13 @@ const getLLMModel = (modelName, config, schema = null) => {
     // Resolve `temperature` with presence/support/range handling (see
     // resolveTemperatureSetting). Applied uniformly to every provider below.
     const modelSettings = resolveTemperatureSetting(modelName, config);
+    // Native web search (see buildWebSearchTool). The tool is bound to the model
+    // so both `.invoke()` and `.stream()` pick it up; the provider runs the search
+    // server-side within the same request, so no client-side agent loop is needed.
+    const webSearchOptions = getWebSearchOptions(config);
+    const webSearchTool = webSearchOptions
+        ? buildWebSearchTool(modelName, webSearchOptions)
+        : null;
     // Claude models (Anthropic)
     if (modelName.startsWith("claude-")) {
         // Anthropic's SDK rejects non-streamed requests when max_tokens is large
@@ -658,7 +893,7 @@ const getLLMModel = (modelName, config, schema = null) => {
                 },
             }
             : {};
-        return new anthropic_1.ChatAnthropic({
+        const model = new anthropic_1.ChatAnthropic({
             apiKey: config.anthropicAPIKey,
             maxTokens,
             modelName: modelName,
@@ -667,6 +902,7 @@ const getLLMModel = (modelName, config, schema = null) => {
             ...outputConfig,
             ...modelSettings,
         });
+        return webSearchTool ? model.bindTools([webSearchTool]) : model;
     }
     // Gemini models (Google)
     else if (modelName.startsWith("gemini-")) {
@@ -679,6 +915,11 @@ const getLLMModel = (modelName, config, schema = null) => {
             ...(schema ? { json: true } : {}),
             ...modelSettings,
         });
+        // Combining grounding with structured output requires Gemini 3 or later;
+        // Gemini 1.5/2.x reject `responseSchema` alongside `googleSearch` with a 400.
+        const bound = webSearchTool
+            ? model.bindTools([webSearchTool])
+            : model;
         // `responseSchema` additionally constrains the output shape. It is a
         // call-time option (not a constructor field), so it is bound onto the model
         // via `withConfig`. Gemini's schema is an OpenAPI 3.0 subset, so
@@ -686,9 +927,9 @@ const getLLMModel = (modelName, config, schema = null) => {
         // parse/validate pipeline is unchanged.
         if (schema) {
             const jsonSchema = sanitizeGeminiSchema(buildJsonSchema(schema));
-            return model.withConfig({ responseSchema: jsonSchema });
+            return bound.withConfig({ responseSchema: jsonSchema });
         }
-        return model;
+        return bound;
     }
     // GPT models (OpenAI)
     else if (modelName.startsWith("gpt-")) {
@@ -696,23 +937,41 @@ const getLLMModel = (modelName, config, schema = null) => {
             apiKey: config.openAIAPIKey,
             max_tokens: config.maxTokens || 200000,
             modelName: modelName,
+            // `web_search` is a hosted Responses API tool, so the request has to go to
+            // `/v1/responses` rather than `/v1/chat/completions`.
+            ...(webSearchTool ? { useResponsesApi: true } : {}),
             ...modelSettings,
         };
-        // Use native response_format with JSON schema for structured output
+        // Use native structured output with a JSON schema. The two endpoints spell
+        // the same thing differently — Chat Completions takes `response_format`,
+        // the Responses API takes `text.format` with the schema flattened one level
+        // — and `modelKwargs` is spread verbatim into whichever request is built.
         if (schema) {
             const jsonSchema = strictifyJsonSchema(buildJsonSchema(schema));
-            openAISettings.modelKwargs = {
-                response_format: {
-                    type: "json_schema",
-                    json_schema: {
-                        name: "response_schema",
-                        strict: true,
-                        schema: jsonSchema,
+            openAISettings.modelKwargs = webSearchTool
+                ? {
+                    text: {
+                        format: {
+                            type: "json_schema",
+                            name: "response_schema",
+                            strict: true,
+                            schema: jsonSchema,
+                        },
                     },
-                },
-            };
+                }
+                : {
+                    response_format: {
+                        type: "json_schema",
+                        json_schema: {
+                            name: "response_schema",
+                            strict: true,
+                            schema: jsonSchema,
+                        },
+                    },
+                };
         }
-        return new openai_1.ChatOpenAI(openAISettings);
+        const model = new openai_1.ChatOpenAI(openAISettings);
+        return webSearchTool ? model.bindTools([webSearchTool]) : model;
     }
     // OpenAI-compatible providers: DeepSeek, Kimi (Moonshot), GLM (Zhipu)
     const openAICompatible = getOpenAICompatibleProvider(modelName, config);
@@ -741,11 +1000,18 @@ const getLLMModel = (modelName, config, schema = null) => {
  * @returns A configured LangChain agent instance ready to be run with `runAgent`
  */
 const createAgent = (name, modelName, systemPrompt, tools = [], responseFormat, config) => {
+    // Native web search joins the agent's tool list instead of being bound inside
+    // `getLLMModel`: the agent binds its own tools to the model, which would drop
+    // anything already bound there.
+    const webSearchOptions = getWebSearchOptions(config);
+    const webSearchTool = webSearchOptions
+        ? buildWebSearchTool(modelName, webSearchOptions)
+        : null;
     const agent = (0, langchain_1.createAgent)({
         name: name,
-        model: getLLMModel(modelName, config),
+        model: getLLMModel(modelName, { ...config, webSearch: null }),
         systemPrompt: systemPrompt.trim(),
-        tools,
+        tools: webSearchTool ? [...tools, webSearchTool] : tools,
         ...(responseFormat ? { responseFormat: responseFormat } : {}),
     });
     return agent;
@@ -832,6 +1098,13 @@ const runAgent = async (agent, prompt, config, onProgress = null, usageTracker =
         }
     }
     updateUsageTracker(usageTracker, modelName, sumAgentResponseUsage(response), config);
+    // Web-search activity is spread across the agent's messages — one search may
+    // be reported by the message that ran it and cited by a later one.
+    const webSearchUsage = createWebSearchUsage();
+    for (const message of response?.messages || []) {
+        collectWebSearchUsage(message, webSearchUsage);
+    }
+    updateWebSearchUsageTracker(usageTracker, modelName, webSearchUsage, config);
     const endTime = Date.now();
     const duration = endTime - startTime;
     logger_js_1.default.log(null, logger_js_1.default.levels.info, `Agent "${agent.options?.name}" completed in ${Math.round(duration / 1000)} seconds.`);
@@ -1068,10 +1341,16 @@ const buildValidationRetryMessages = (priorMessages, rawContent, validationError
  *
  * When `expectsJsonResponse` is `true`, JSON escape instructions are prepended to the
  * system prompt and the parsed result is optionally validated against `schema`.
+ *
+ * Setting `config.webSearch` enables the provider's native web search tool in every
+ * mode (see `buildWebSearchTool`). The provider runs the search server-side inside the
+ * same request, so the return contract is unchanged; the searches performed and the
+ * sources cited are recorded on `usageTracker`.
  * @param modelName - The model identifier, e.g. `"gpt-4o"`, `"claude-3-5-sonnet"`,
  *   `"gemini-1.5-pro"`
  * @param config - Configuration object with API keys, `temperature`, optional `agentic`
- *   flag, and optional `recursionLimit`
+ *   flag, optional `recursionLimit`, and optional `webSearch` (`true` or a
+ *   `WebSearchConfig`)
  * @param prompt - The prompt to send; either a plain string (user message only) or an
  *   array of `{ role, content }` message objects
  * @param onProgressReport - Optional async callback invoked with `{ message, progress }`
@@ -1133,12 +1412,9 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
             throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, "Agent returned no messages");
         }
         const lastMessage = messages[messages.length - 1];
-        let rawContent = lastMessage?.content || "";
-        // Handle array content blocks (e.g., from Gemini/Claude agent responses)
-        if (Array.isArray(rawContent)) {
-            const textBlock = rawContent.find((block) => typeof block === "object" && block.type === "text");
-            rawContent = textBlock?.text || "";
-        }
+        // Flattens the array content blocks that Gemini/Claude agent responses and
+        // any server-tool turn (e.g. web search) return.
+        const rawContent = extractTextContent(lastMessage?.content);
         // If not expecting JSON, return raw content directly
         if (!expectsJsonResponse) {
             return rawContent;
@@ -1260,6 +1536,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 output_tokens: 0,
                 total_tokens: 0,
             };
+            let webSearchUsage = createWebSearchUsage();
             // Inner loop: wait + retry on 429 around stream setup and consumption.
             // Usage is only recorded on a successful stream — partial streams that
             // error out with a rate limit are not counted. A 429 fired mid-stream
@@ -1269,6 +1546,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 rawContent = "";
                 chunkCount = 0;
                 streamUsage = { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
+                webSearchUsage = createWebSearchUsage();
                 try {
                     // Honour caller cancellation: passing the signal tears down the
                     // upstream HTTP request so a cancelled call stops billing tokens.
@@ -1281,16 +1559,16 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                             throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.BAD_REQUEST, "Request cancelled by caller");
                         }
                         accumulateChunkUsage(streamUsage, chunk);
-                        const content = chunk?.content || chunk;
-                        if (typeof content === "string") {
-                            rawContent += content;
-                            chunkCount++;
-                            if (chunkCount % progressReportInterval === 0) {
-                                await onProgressReport({
-                                    message: "Generating content...",
-                                    progress: Math.min(calcCurrentProgress(), maxPercent - 5),
-                                });
-                            }
+                        collectWebSearchUsage(chunk, webSearchUsage);
+                        // Counting every chunk (not just the ones carrying text) keeps
+                        // progress ticking through the pause while a search runs.
+                        chunkCount++;
+                        rawContent += extractTextContent(chunk?.content ?? chunk);
+                        if (chunkCount % progressReportInterval === 0) {
+                            await onProgressReport({
+                                message: "Generating content...",
+                                progress: Math.min(calcCurrentProgress(), maxPercent - 5),
+                            });
                         }
                     }
                     break; // stream completed without 429
@@ -1313,6 +1591,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 }
             }
             updateUsageTracker(usageTracker, modelName, streamUsage, config);
+            updateWebSearchUsageTracker(usageTracker, modelName, webSearchUsage, config);
             if (!rawContent) {
                 throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, "LLM returned no content");
             }
@@ -1417,7 +1696,11 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 }
             }
             updateUsageTracker(usageTracker, modelName, extractUsageFromInvoke(response), config);
-            const rawContent = response?.content || response;
+            const webSearchUsage = createWebSearchUsage();
+            collectWebSearchUsage(response, webSearchUsage);
+            updateWebSearchUsageTracker(usageTracker, modelName, webSearchUsage, config);
+            // Flattened because a server-tool turn returns content blocks, not a string.
+            const rawContent = extractTextContent(response?.content ?? response);
             // If not expecting JSON, return raw content directly
             if (!expectsJsonResponse) {
                 return rawContent;

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) },