@stackfactor/agent-utils 1.1.7 → 1.2.0

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}\n\nmessage HealthCheckResponse {\n  bool   ok                = 1;\n  bool   backend_reachable = 2;\n  string version           = 3;\n  string message           = 4;\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}\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,+pCA2CjB,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,09DA6DjB,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

@@ -69,13 +69,31 @@ message HealthCheckRequest {
   // Optional JSON carrying { authToken } for the deep backend-callback check.
   string request_json = 1;
   bool   deep         = 2;
+  // Deep check only: repo-relative path to the agent's self-check module to run
+  // (e.g. "src/check.js"). Empty → fall back to the conventional "src/check.js".
+  string check_code   = 3;
+  // Deep check only: JSON of the resolved agent config (constantsAndVars/
+  // secrets) made available to the self-check as ctx.config. May be empty.
+  string config_json  = 4;
+}
+
+// One result row from the agent's self-check module. The agent owns only its
+// own checks; reachability/ingress/version-drift rows are synthesised backend-
+// side. severity is optional: "warn" marks a failing check as non-blocking;
+// empty or "error" is blocking.
+message CheckResult {
+  string name     = 1;
+  bool   ok       = 2;
+  string detail   = 3;
+  string severity = 4;
 }
 
 message HealthCheckResponse {
-  bool   ok                = 1;
-  bool   backend_reachable = 2;
-  string version           = 3;
-  string message           = 4;
+  bool   ok                  = 1;
+  bool   backend_reachable   = 2;
+  string version             = 3;
+  string message             = 4;
+  repeated CheckResult checks = 5;
 }
 
 message Update {

package/dist/cjs/client.d.ts

@@ -48,11 +48,29 @@ export interface CheckAgentOptions {
     deep?: boolean;
     /** StackFactor session token used for the deep backend-callback check. */
     authToken?: string;
+    /**
+     * Deep check only: repo-relative path to the agent's self-check module
+     * (e.g. "src/check.js"). Empty → the agent falls back to "src/check.js".
+     */
+    checkCode?: string;
+    /**
+     * Deep check only: resolved agent config (constantsAndVars/secrets) exposed to
+     * the self-check as `ctx.config`. Serialised to JSON on the wire.
+     */
+    config?: any;
     /** Call deadline; defaults to 15s (a health probe should be quick). */
     deadlineMs?: number;
 }
+/** One self-check row reported by the agent's check module. */
+export interface AgentCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+    /** "warn" → non-blocking; empty/"error" → blocking. */
+    severity: string;
+}
 export interface AgentHealth {
-    /** The agent answered (and, for a deep check, auth succeeded). */
+    /** The agent answered (and, for a deep check, auth + checks succeeded). */
     ok: boolean;
     /** Deep check only: the agent reached the StackFactor backend (BACKEND_URL). */
     backendReachable: boolean;
@@ -60,6 +78,8 @@ export interface AgentHealth {
     version: string;
     /** Human-readable detail — carries the failure reason when `ok` is false. */
     message: string;
+    /** Deep check only: the agent's own self-check rows (empty if none shipped). */
+    checks: AgentCheck[];
 }
 /**
  * Probes a deployed agent's `Agent.HealthCheck` (unary). Resolves with the

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;AAqCD;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GACpB,UAAU,MAAM,EAChB,SAAS,mBAAmB,EAC5B,UAAS,gBAAqB,KAC7B,OAAO,CAAC,GAAG,CAyDV,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,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,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;CACjB;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GACrB,UAAU,MAAM,EAChB,UAAS,iBAAsB,KAC9B,OAAO,CAAC,WAAW,CAkClB,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;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;AAqCD;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GACpB,UAAU,MAAM,EAChB,SAAS,mBAAmB,EAC5B,UAAS,gBAAqB,KAC7B,OAAO,CAAC,GAAG,CAyDV,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,CA6ClB,CAAC"}

package/dist/cjs/client.js

@@ -146,6 +146,8 @@ const checkAgent = (agentUrl, options = {}) => new Promise((resolve, reject) =>
     const request = {
         request_json: JSON.stringify({ authToken: options.authToken }),
         deep: !!options.deep,
+        check_code: options.checkCode ?? "",
+        config_json: options.config === undefined ? "" : JSON.stringify(options.config),
     };
     client.HealthCheck(request, { deadline: Date.now() + (options.deadlineMs ?? DEFAULT_HEALTH_DEADLINE_MS) }, (error, response) => {
         try {
@@ -163,6 +165,14 @@ const checkAgent = (agentUrl, options = {}) => new Promise((resolve, reject) =>
             backendReachable: !!response?.backend_reachable,
             version: response?.version ?? "",
             message: response?.message ?? "",
+            checks: Array.isArray(response?.checks)
+                ? response.checks.map((check) => ({
+                    name: check?.name ?? "",
+                    ok: !!check?.ok,
+                    detail: check?.detail ?? "",
+                    severity: check?.severity ?? "error",
+                }))
+                : [],
         });
     });
 });

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;AAMtC;;;;;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,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC,CAAC;AAElF,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;AAkDD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAAI,MAAM,SAAS,EAAE,UAAS,YAAiB,KAAG,IAAI,CAAC,MAuIxE,CAAC"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AA+ItC;;;;;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;AAkDD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAChB,MAAM,SAAS,EACf,UAAS,YAAiB,KACzB,IAAI,CAAC,MAuKP,CAAC"}

package/dist/cjs/serve.js

@@ -38,10 +38,126 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.serve = void 0;
 const grpc = __importStar(require("@grpc/grpc-js"));
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
 const client_api_1 = require("@stackfactor/client-api");
 const logger_js_1 = __importDefault(require("./logger.js"));
 const agentProto_js_1 = require("./agentProto.js");
 const runtimeContext_js_1 = require("./runtimeContext.js");
+// The conventional self-check module run on a deep HealthCheck when the caller
+// doesn't specify `check_code`. Resolved relative to the agent's app root.
+const DEFAULT_CHECK_PATH = "src/check.js";
+// Hard cap on a self-check; the agent receives this as its AbortSignal so its
+// 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
+ * path that escapes it or is absolute (the path may originate from the
+ * integration config, so treat it as untrusted). Returns null when unsafe.
+ */
+const resolveCheckPath = (checkCode) => {
+    const root = process.cwd();
+    const rel = (checkCode || "").trim() || DEFAULT_CHECK_PATH;
+    const dest = (0, node_path_1.resolve)(root, rel);
+    const back = (0, node_path_1.relative)(root, dest);
+    if (back === "" || back.startsWith("..") || (0, node_path_1.isAbsolute)(back)) {
+        return null;
+    }
+    return dest;
+};
+/** Coerces whatever the agent's check returned into well-formed CheckResult[]. */
+const normalizeChecks = (raw) => {
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw
+        .filter((entry) => entry && typeof entry.name === "string")
+        .map((entry) => ({
+        name: entry.name,
+        ok: !!entry.ok,
+        detail: typeof entry.detail === "string" ? entry.detail : "",
+        severity: entry.severity === "warn" ? "warn" : "error",
+    }));
+};
+/**
+ * Loads and runs the agent's self-check module (`check_code` or the default
+ * `src/check.js`). The check follows the same programming model as `main`: it
+ * receives the request {@link AbortSignal} and reads `config` / `request`
+ * (incl. `request.session`) from the per-request globals (bound here via
+ * {@link runWithContext}); the logger is imported. The agent owns only its own
+ * checks — reachability/version rows are synthesised backend-side. Never throws:
+ * a missing module yields no rows; a load error, bad export, thrown error, or
+ * timeout collapses to a single failed `self_check` row.
+ */
+const runSelfCheck = async (checkCode, config, session) => {
+    const modulePath = resolveCheckPath(checkCode);
+    if (!modulePath || !(0, node_fs_1.existsSync)(modulePath)) {
+        return []; // no self-check module shipped — baseline checks only
+    }
+    let checkFn;
+    try {
+        const mod = await Promise.resolve(`${(0, node_url_1.pathToFileURL)(modulePath).href}`).then(s => __importStar(require(s)));
+        const exported = mod?.default ?? mod;
+        checkFn =
+            typeof exported === "function" ? exported : exported?.check ?? exported?.default;
+    }
+    catch (error) {
+        return [
+            {
+                name: "self_check",
+                ok: false,
+                detail: `failed to load check module: ${error?.message ?? error}`,
+                severity: "error",
+            },
+        ];
+    }
+    if (typeof checkFn !== "function") {
+        return [
+            {
+                name: "self_check",
+                ok: false,
+                detail: "check module does not export a function",
+                severity: "error",
+            },
+        ];
+    }
+    const abort = new AbortController();
+    const timer = setTimeout(() => abort.abort(), SELF_CHECK_TIMEOUT_MS);
+    // Bind the same per-request globals main() sees (config, request.session, …)
+    // so the check reads them identically; it receives the AbortSignal as its arg.
+    const requestContext = {
+        config,
+        params: {},
+        request: { session },
+        event: 0,
+        onProgress: null,
+        signal: abort.signal,
+        session,
+    };
+    try {
+        const raw = await Promise.race([
+            (0, runtimeContext_js_1.runWithContext)(requestContext, () => Promise.resolve(checkFn(abort.signal))),
+            new Promise((_, reject) => {
+                abort.signal.addEventListener("abort", () => reject(new Error(`self-check timed out after ${SELF_CHECK_TIMEOUT_MS}ms`)));
+            }),
+        ]);
+        return normalizeChecks(raw);
+    }
+    catch (error) {
+        return [
+            {
+                name: "self_check",
+                ok: false,
+                detail: error?.message ?? String(error),
+                severity: "error",
+            },
+        ];
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
 /** Marks an auth failure so the handler can map it to gRPC UNAUTHENTICATED. */
 class UnauthenticatedError extends Error {
 }
@@ -54,13 +170,13 @@ class UnauthenticatedError extends Error {
 const defaultAuthenticate = async (request) => {
     const token = request?.authToken ?? request?.authorization;
     if (!token) {
-        throw new UnauthenticatedError("Missing auth token");
+        throw new UnauthenticatedError("Missing StackFactor auth token");
     }
     try {
         return await client_api_1.session.getSession(token);
     }
     catch (error) {
-        throw new UnauthenticatedError(`Invalid auth token: ${error?.message ?? error}`);
+        throw new UnauthenticatedError(`Invalid StackFactor auth token: ${error?.message ?? error}`);
     }
 };
 const safeParse = (value, fallback) => {
@@ -151,7 +267,9 @@ const serve = (main, options = {}) => {
             try {
                 const result = await (0, runtimeContext_js_1.runWithContext)(context, () => main(abort.signal));
                 if (!abort.signal.aborted) {
-                    call.write({ result: { result_json: JSON.stringify(result ?? null) } });
+                    call.write({
+                        result: { result_json: JSON.stringify(result ?? null) },
+                    });
                 }
             }
             catch (error) {
@@ -173,19 +291,40 @@ const serve = (main, options = {}) => {
     //    validates the StackFactor token against BACKEND_URL — surfacing a broken
     //    backend callback (the `ECONNREFUSED 127.0.0.1:443` class) before it bites.
     const healthCheck = (call, callback) => {
-        const respond = (ok, backendReachable, message) => callback(null, {
+        const respond = (ok, backendReachable, message, checks = []) => callback(null, {
             ok,
             backend_reachable: backendReachable,
             version: process.env.AGENT_VERSION ?? "",
             message,
+            checks,
         });
+        // Shallow: confirm the process is up + ingress auth (the caller reached us).
         if (!call.request?.deep) {
             respond(true, false, "ok");
             return;
         }
-        void authenticate(safeParse(call.request?.request_json, {}))
-            .then(() => respond(true, true, "ok"))
-            .catch((error) => respond(false, false, error?.message ?? "auth failed"));
+        // Deep: run the same auth path Execute uses (validates the StackFactor token
+        // against BACKEND_URL) AND the agent's own self-check module, then roll the
+        // two up into a single verdict. Warn-severity check failures don't block ok.
+        const request = safeParse(call.request?.request_json, {});
+        const checkCode = String(call.request?.check_code ?? "");
+        const checkConfig = safeParse(call.request?.config_json, {});
+        void (async () => {
+            let backendReachable = false;
+            let session = null;
+            let message = "ok";
+            try {
+                session = await authenticate(request);
+                backendReachable = true;
+            }
+            catch (error) {
+                message = error?.message ?? "auth failed";
+            }
+            const checks = await runSelfCheck(checkCode, checkConfig, session);
+            const ok = backendReachable &&
+                checks.every((check) => check.ok || check.severity === "warn");
+            respond(ok, backendReachable, message, checks);
+        })();
     };
     const server = new grpc.Server();
     server.addService((0, agentProto_js_1.loadAgentService)(), {

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}\n\nmessage HealthCheckResponse {\n  bool   ok                = 1;\n  bool   backend_reachable = 2;\n  string version           = 3;\n  string message           = 4;\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}\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,+pCA2CjB,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,09DA6DjB,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

@@ -33,13 +33,31 @@ message HealthCheckRequest {
   // Optional JSON carrying { authToken } for the deep backend-callback check.
   string request_json = 1;
   bool   deep         = 2;
+  // Deep check only: repo-relative path to the agent's self-check module to run
+  // (e.g. "src/check.js"). Empty → fall back to the conventional "src/check.js".
+  string check_code   = 3;
+  // Deep check only: JSON of the resolved agent config (constantsAndVars/
+  // secrets) made available to the self-check as ctx.config. May be empty.
+  string config_json  = 4;
+}
+
+// One result row from the agent's self-check module. The agent owns only its
+// own checks; reachability/ingress/version-drift rows are synthesised backend-
+// side. severity is optional: "warn" marks a failing check as non-blocking;
+// empty or "error" is blocking.
+message CheckResult {
+  string name     = 1;
+  bool   ok       = 2;
+  string detail   = 3;
+  string severity = 4;
 }
 
 message HealthCheckResponse {
-  bool   ok                = 1;
-  bool   backend_reachable = 2;
-  string version           = 3;
-  string message           = 4;
+  bool   ok                  = 1;
+  bool   backend_reachable   = 2;
+  string version             = 3;
+  string message             = 4;
+  repeated CheckResult checks = 5;
 }
 
 message Update {

package/dist/esm/client.d.ts

@@ -48,11 +48,29 @@ export interface CheckAgentOptions {
     deep?: boolean;
     /** StackFactor session token used for the deep backend-callback check. */
     authToken?: string;
+    /**
+     * Deep check only: repo-relative path to the agent's self-check module
+     * (e.g. "src/check.js"). Empty → the agent falls back to "src/check.js".
+     */
+    checkCode?: string;
+    /**
+     * Deep check only: resolved agent config (constantsAndVars/secrets) exposed to
+     * the self-check as `ctx.config`. Serialised to JSON on the wire.
+     */
+    config?: any;
     /** Call deadline; defaults to 15s (a health probe should be quick). */
     deadlineMs?: number;
 }
+/** One self-check row reported by the agent's check module. */
+export interface AgentCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+    /** "warn" → non-blocking; empty/"error" → blocking. */
+    severity: string;
+}
 export interface AgentHealth {
-    /** The agent answered (and, for a deep check, auth succeeded). */
+    /** The agent answered (and, for a deep check, auth + checks succeeded). */
     ok: boolean;
     /** Deep check only: the agent reached the StackFactor backend (BACKEND_URL). */
     backendReachable: boolean;
@@ -60,6 +78,8 @@ export interface AgentHealth {
     version: string;
     /** Human-readable detail — carries the failure reason when `ok` is false. */
     message: string;
+    /** Deep check only: the agent's own self-check rows (empty if none shipped). */
+    checks: AgentCheck[];
 }
 /**
  * Probes a deployed agent's `Agent.HealthCheck` (unary). Resolves with the

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;AAqCD;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GACpB,UAAU,MAAM,EAChB,SAAS,mBAAmB,EAC5B,UAAS,gBAAqB,KAC7B,OAAO,CAAC,GAAG,CAyDV,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,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,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;CACjB;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GACrB,UAAU,MAAM,EAChB,UAAS,iBAAsB,KAC9B,OAAO,CAAC,WAAW,CAkClB,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;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;AAqCD;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GACpB,UAAU,MAAM,EAChB,SAAS,mBAAmB,EAC5B,UAAS,gBAAqB,KAC7B,OAAO,CAAC,GAAG,CAyDV,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,CA6ClB,CAAC"}

package/dist/esm/client.js

@@ -109,6 +109,8 @@ export const checkAgent = (agentUrl, options = {}) => new Promise((resolve, reje
     const request = {
         request_json: JSON.stringify({ authToken: options.authToken }),
         deep: !!options.deep,
+        check_code: options.checkCode ?? "",
+        config_json: options.config === undefined ? "" : JSON.stringify(options.config),
     };
     client.HealthCheck(request, { deadline: Date.now() + (options.deadlineMs ?? DEFAULT_HEALTH_DEADLINE_MS) }, (error, response) => {
         try {
@@ -126,6 +128,14 @@ export const checkAgent = (agentUrl, options = {}) => new Promise((resolve, reje
             backendReachable: !!response?.backend_reachable,
             version: response?.version ?? "",
             message: response?.message ?? "",
+            checks: Array.isArray(response?.checks)
+                ? response.checks.map((check) => ({
+                    name: check?.name ?? "",
+                    ok: !!check?.ok,
+                    detail: check?.detail ?? "",
+                    severity: check?.severity ?? "error",
+                }))
+                : [],
         });
     });
 });

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;AAMtC;;;;;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,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC,CAAC;AAElF,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;AAkDD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAAI,MAAM,SAAS,EAAE,UAAS,YAAiB,KAAG,IAAI,CAAC,MAuIxE,CAAC"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AA+ItC;;;;;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;AAkDD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAChB,MAAM,SAAS,EACf,UAAS,YAAiB,KACzB,IAAI,CAAC,MAuKP,CAAC"}

package/dist/esm/serve.js

@@ -1,8 +1,124 @@
 import * as grpc from "@grpc/grpc-js";
+import { existsSync } from "node:fs";
+import { resolve, relative, isAbsolute } from "node:path";
+import { pathToFileURL } from "node:url";
 import { session as clientSession } from "@stackfactor/client-api";
 import logger from "./logger.js";
 import { loadAgentService } from "./agentProto.js";
 import { runWithContext, installGlobals } from "./runtimeContext.js";
+// The conventional self-check module run on a deep HealthCheck when the caller
+// doesn't specify `check_code`. Resolved relative to the agent's app root.
+const DEFAULT_CHECK_PATH = "src/check.js";
+// Hard cap on a self-check; the agent receives this as its AbortSignal so its
+// 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
+ * path that escapes it or is absolute (the path may originate from the
+ * integration config, so treat it as untrusted). Returns null when unsafe.
+ */
+const resolveCheckPath = (checkCode) => {
+    const root = process.cwd();
+    const rel = (checkCode || "").trim() || DEFAULT_CHECK_PATH;
+    const dest = resolve(root, rel);
+    const back = relative(root, dest);
+    if (back === "" || back.startsWith("..") || isAbsolute(back)) {
+        return null;
+    }
+    return dest;
+};
+/** Coerces whatever the agent's check returned into well-formed CheckResult[]. */
+const normalizeChecks = (raw) => {
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw
+        .filter((entry) => entry && typeof entry.name === "string")
+        .map((entry) => ({
+        name: entry.name,
+        ok: !!entry.ok,
+        detail: typeof entry.detail === "string" ? entry.detail : "",
+        severity: entry.severity === "warn" ? "warn" : "error",
+    }));
+};
+/**
+ * Loads and runs the agent's self-check module (`check_code` or the default
+ * `src/check.js`). The check follows the same programming model as `main`: it
+ * receives the request {@link AbortSignal} and reads `config` / `request`
+ * (incl. `request.session`) from the per-request globals (bound here via
+ * {@link runWithContext}); the logger is imported. The agent owns only its own
+ * checks — reachability/version rows are synthesised backend-side. Never throws:
+ * a missing module yields no rows; a load error, bad export, thrown error, or
+ * timeout collapses to a single failed `self_check` row.
+ */
+const runSelfCheck = async (checkCode, config, session) => {
+    const modulePath = resolveCheckPath(checkCode);
+    if (!modulePath || !existsSync(modulePath)) {
+        return []; // no self-check module shipped — baseline checks only
+    }
+    let checkFn;
+    try {
+        const mod = await import(pathToFileURL(modulePath).href);
+        const exported = mod?.default ?? mod;
+        checkFn =
+            typeof exported === "function" ? exported : exported?.check ?? exported?.default;
+    }
+    catch (error) {
+        return [
+            {
+                name: "self_check",
+                ok: false,
+                detail: `failed to load check module: ${error?.message ?? error}`,
+                severity: "error",
+            },
+        ];
+    }
+    if (typeof checkFn !== "function") {
+        return [
+            {
+                name: "self_check",
+                ok: false,
+                detail: "check module does not export a function",
+                severity: "error",
+            },
+        ];
+    }
+    const abort = new AbortController();
+    const timer = setTimeout(() => abort.abort(), SELF_CHECK_TIMEOUT_MS);
+    // Bind the same per-request globals main() sees (config, request.session, …)
+    // so the check reads them identically; it receives the AbortSignal as its arg.
+    const requestContext = {
+        config,
+        params: {},
+        request: { session },
+        event: 0,
+        onProgress: null,
+        signal: abort.signal,
+        session,
+    };
+    try {
+        const raw = await Promise.race([
+            runWithContext(requestContext, () => Promise.resolve(checkFn(abort.signal))),
+            new Promise((_, reject) => {
+                abort.signal.addEventListener("abort", () => reject(new Error(`self-check timed out after ${SELF_CHECK_TIMEOUT_MS}ms`)));
+            }),
+        ]);
+        return normalizeChecks(raw);
+    }
+    catch (error) {
+        return [
+            {
+                name: "self_check",
+                ok: false,
+                detail: error?.message ?? String(error),
+                severity: "error",
+            },
+        ];
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
 /** Marks an auth failure so the handler can map it to gRPC UNAUTHENTICATED. */
 class UnauthenticatedError extends Error {
 }
@@ -15,13 +131,13 @@ class UnauthenticatedError extends Error {
 const defaultAuthenticate = async (request) => {
     const token = request?.authToken ?? request?.authorization;
     if (!token) {
-        throw new UnauthenticatedError("Missing auth token");
+        throw new UnauthenticatedError("Missing StackFactor auth token");
     }
     try {
         return await clientSession.getSession(token);
     }
     catch (error) {
-        throw new UnauthenticatedError(`Invalid auth token: ${error?.message ?? error}`);
+        throw new UnauthenticatedError(`Invalid StackFactor auth token: ${error?.message ?? error}`);
     }
 };
 const safeParse = (value, fallback) => {
@@ -112,7 +228,9 @@ export const serve = (main, options = {}) => {
             try {
                 const result = await runWithContext(context, () => main(abort.signal));
                 if (!abort.signal.aborted) {
-                    call.write({ result: { result_json: JSON.stringify(result ?? null) } });
+                    call.write({
+                        result: { result_json: JSON.stringify(result ?? null) },
+                    });
                 }
             }
             catch (error) {
@@ -134,19 +252,40 @@ export const serve = (main, options = {}) => {
     //    validates the StackFactor token against BACKEND_URL — surfacing a broken
     //    backend callback (the `ECONNREFUSED 127.0.0.1:443` class) before it bites.
     const healthCheck = (call, callback) => {
-        const respond = (ok, backendReachable, message) => callback(null, {
+        const respond = (ok, backendReachable, message, checks = []) => callback(null, {
             ok,
             backend_reachable: backendReachable,
             version: process.env.AGENT_VERSION ?? "",
             message,
+            checks,
         });
+        // Shallow: confirm the process is up + ingress auth (the caller reached us).
         if (!call.request?.deep) {
             respond(true, false, "ok");
             return;
         }
-        void authenticate(safeParse(call.request?.request_json, {}))
-            .then(() => respond(true, true, "ok"))
-            .catch((error) => respond(false, false, error?.message ?? "auth failed"));
+        // Deep: run the same auth path Execute uses (validates the StackFactor token
+        // against BACKEND_URL) AND the agent's own self-check module, then roll the
+        // two up into a single verdict. Warn-severity check failures don't block ok.
+        const request = safeParse(call.request?.request_json, {});
+        const checkCode = String(call.request?.check_code ?? "");
+        const checkConfig = safeParse(call.request?.config_json, {});
+        void (async () => {
+            let backendReachable = false;
+            let session = null;
+            let message = "ok";
+            try {
+                session = await authenticate(request);
+                backendReachable = true;
+            }
+            catch (error) {
+                message = error?.message ?? "auth failed";
+            }
+            const checks = await runSelfCheck(checkCode, checkConfig, session);
+            const ok = backendReachable &&
+                checks.every((check) => check.ok || check.severity === "warn");
+            respond(ok, backendReachable, message, checks);
+        })();
     };
     const server = new grpc.Server();
     server.addService(loadAgentService(), {

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.1.7",
+  "version": "1.2.0",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",