@stackfactor/agent-utils 1.1.2 → 1.1.4

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}\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 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}\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";
 /**
  * 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,smBA2BjB,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,+pCA2CjB,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

@@ -52,6 +52,9 @@ package stackfactor.agent.v1;
 
 service Agent {
   rpc Execute(ExecuteRequest) returns (stream Update);
+  // Liveness/health probe served by serve() itself — no agent code required.
+  // deep=true also exercises the StackFactor auth callback (BACKEND_URL).
+  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
 }
 
 message ExecuteRequest {
@@ -62,6 +65,19 @@ message ExecuteRequest {
   int32  event        = 5;
 }
 
+message HealthCheckRequest {
+  // Optional JSON carrying { authToken } for the deep backend-callback check.
+  string request_json = 1;
+  bool   deep         = 2;
+}
+
+message HealthCheckResponse {
+  bool   ok                = 1;
+  bool   backend_reachable = 2;
+  string version           = 3;
+  string message           = 4;
+}
+
 message Update {
   oneof payload {
     Progress  progress = 1;

package/dist/cjs/client.d.ts

@@ -38,4 +38,36 @@ export interface CallAgentOptions {
  * @param request - The `ExecuteRequest` (its `request_json` carries `authToken`).
  */
 export declare const callAgent: (agentUrl: string, request: AgentExecuteRequest, options?: CallAgentOptions) => Promise<any>;
+export interface CheckAgentOptions {
+    /** Google ID token (audience = agent URL) to pass Cloud Run ingress. */
+    idToken?: string;
+    /**
+     * When true, the agent additionally validates `authToken` against its
+     * BACKEND_URL — proving the full auth flow (not just that it's reachable).
+     */
+    deep?: boolean;
+    /** StackFactor session token used for the deep backend-callback check. */
+    authToken?: string;
+    /** Call deadline; defaults to 15s (a health probe should be quick). */
+    deadlineMs?: number;
+}
+export interface AgentHealth {
+    /** The agent answered (and, for a deep check, auth succeeded). */
+    ok: boolean;
+    /** Deep check only: the agent reached the StackFactor backend (BACKEND_URL). */
+    backendReachable: boolean;
+    /** Agent build/version string, when the agent reports one. */
+    version: string;
+    /** Human-readable detail — carries the failure reason when `ok` is false. */
+    message: string;
+}
+/**
+ * Probes a deployed agent's `Agent.HealthCheck` (unary). Resolves with the
+ * agent's health; rejects on transport/ingress errors (e.g. gRPC UNIMPLEMENTED
+ * when the agent predates this RPC — callers should treat that as "redeploy to
+ * enable", not "down").
+ *
+ * @param agentUrl - The agent's Cloud Run URL (https://…run.app).
+ */
+export declare const checkAgent: (agentUrl: string, options?: CheckAgentOptions) => Promise<AgentHealth>;
 //# sourceMappingURL=client.d.ts.map

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"}
+{"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"}

package/dist/cjs/client.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.callAgent = void 0;
+exports.checkAgent = exports.callAgent = void 0;
 const grpc = __importStar(require("@grpc/grpc-js"));
 const agentProto_js_1 = require("./agentProto.js");
 const DEFAULT_DEADLINE_MS = 900_000;
@@ -129,3 +129,41 @@ const callAgent = (agentUrl, request, options = {}) => new Promise((resolve, rej
     stream.on("end", () => settle(() => reject(new Error("Agent stream ended without a result or error"))));
 });
 exports.callAgent = callAgent;
+const DEFAULT_HEALTH_DEADLINE_MS = 15_000;
+/**
+ * Probes a deployed agent's `Agent.HealthCheck` (unary). Resolves with the
+ * agent's health; rejects on transport/ingress errors (e.g. gRPC UNIMPLEMENTED
+ * when the agent predates this RPC — callers should treat that as "redeploy to
+ * enable", not "down").
+ *
+ * @param agentUrl - The agent's Cloud Run URL (https://…run.app).
+ */
+const checkAgent = (agentUrl, options = {}) => new Promise((resolve, reject) => {
+    const loaded = (0, agentProto_js_1.loadAgentPackage)();
+    const url = new URL(agentUrl);
+    const address = `${url.hostname}:${url.port || "443"}`;
+    const client = new loaded.stackfactor.agent.v1.Agent(address, buildCredentials(options.idToken));
+    const request = {
+        request_json: JSON.stringify({ authToken: options.authToken }),
+        deep: !!options.deep,
+    };
+    client.HealthCheck(request, { deadline: Date.now() + (options.deadlineMs ?? DEFAULT_HEALTH_DEADLINE_MS) }, (error, response) => {
+        try {
+            client.close();
+        }
+        catch {
+            // ignore close errors
+        }
+        if (error) {
+            reject(error);
+            return;
+        }
+        resolve({
+            ok: !!response?.ok,
+            backendReachable: !!response?.backend_reachable,
+            version: response?.version ?? "",
+            message: response?.message ?? "",
+        });
+    });
+});
+exports.checkAgent = checkAgent;

package/dist/cjs/index.d.ts

@@ -3,7 +3,7 @@ import errorHandling from "./errorHandling.js";
 import langChain from "./langChain.js";
 import logger from "./logger.js";
 import { serve } from "./serve.js";
-import { callAgent } from "./client.js";
+import { callAgent, checkAgent } from "./client.js";
 import * as runtimeContext from "./runtimeContext.js";
 export { constants };
 export { errorHandling };
@@ -11,6 +11,7 @@ export { langChain };
 export { logger };
 export { serve };
 export { callAgent };
-export type { AgentExecuteRequest, CallAgentOptions } from "./client.js";
+export { checkAgent };
+export type { AgentExecuteRequest, CallAgentOptions, CheckAgentOptions, AgentHealth, } from "./client.js";
 export { runtimeContext };
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,MAAM,oBAAoB,CAAC;AAC/C,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEzE,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,MAAM,oBAAoB,CAAC;AAC/C,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/cjs/index.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runtimeContext = exports.callAgent = exports.serve = exports.logger = exports.langChain = exports.errorHandling = exports.constants = void 0;
+exports.runtimeContext = exports.checkAgent = exports.callAgent = exports.serve = exports.logger = exports.langChain = exports.errorHandling = exports.constants = void 0;
 const const_js_1 = __importDefault(require("./const.js"));
 exports.constants = const_js_1.default;
 const errorHandling_js_1 = __importDefault(require("./errorHandling.js"));
@@ -49,5 +49,6 @@ const serve_js_1 = require("./serve.js");
 Object.defineProperty(exports, "serve", { enumerable: true, get: function () { return serve_js_1.serve; } });
 const client_js_1 = require("./client.js");
 Object.defineProperty(exports, "callAgent", { enumerable: true, get: function () { return client_js_1.callAgent; } });
+Object.defineProperty(exports, "checkAgent", { enumerable: true, get: function () { return client_js_1.checkAgent; } });
 const runtimeContext = __importStar(require("./runtimeContext.js"));
 exports.runtimeContext = runtimeContext;

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,MAsGxE,CAAC"}
+{"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"}

package/dist/cjs/serve.js

@@ -166,8 +166,32 @@ const serve = (main, options = {}) => {
         };
         void handle();
     };
+    // Health probe served by the base server — agents get it for free.
+    //  - shallow: confirms the process is up and ingress auth works (the caller
+    //    reached this handler at all).
+    //  - deep: additionally runs the same `authenticate` path Execute uses, which
+    //    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, {
+            ok,
+            backend_reachable: backendReachable,
+            version: process.env.AGENT_VERSION ?? "",
+            message,
+        });
+        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"));
+    };
     const server = new grpc.Server();
-    server.addService((0, agentProto_js_1.loadAgentService)(), { Execute: execute });
+    server.addService((0, agentProto_js_1.loadAgentService)(), {
+        Execute: execute,
+        HealthCheck: healthCheck,
+    });
     // Insecure: Cloud Run terminates TLS at the edge and forwards h2c to the
     // container (requires the service to be deployed with --use-http2).
     server.bindAsync(`${host}:${port}`, grpc.ServerCredentials.createInsecure(), (err, boundPort) => {

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}\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 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}\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";
 /**
  * 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,smBA2BjB,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,+pCA2CjB,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

@@ -16,6 +16,9 @@ package stackfactor.agent.v1;
 
 service Agent {
   rpc Execute(ExecuteRequest) returns (stream Update);
+  // Liveness/health probe served by serve() itself — no agent code required.
+  // deep=true also exercises the StackFactor auth callback (BACKEND_URL).
+  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
 }
 
 message ExecuteRequest {
@@ -26,6 +29,19 @@ message ExecuteRequest {
   int32  event        = 5;
 }
 
+message HealthCheckRequest {
+  // Optional JSON carrying { authToken } for the deep backend-callback check.
+  string request_json = 1;
+  bool   deep         = 2;
+}
+
+message HealthCheckResponse {
+  bool   ok                = 1;
+  bool   backend_reachable = 2;
+  string version           = 3;
+  string message           = 4;
+}
+
 message Update {
   oneof payload {
     Progress  progress = 1;

package/dist/esm/client.d.ts

@@ -38,4 +38,36 @@ export interface CallAgentOptions {
  * @param request - The `ExecuteRequest` (its `request_json` carries `authToken`).
  */
 export declare const callAgent: (agentUrl: string, request: AgentExecuteRequest, options?: CallAgentOptions) => Promise<any>;
+export interface CheckAgentOptions {
+    /** Google ID token (audience = agent URL) to pass Cloud Run ingress. */
+    idToken?: string;
+    /**
+     * When true, the agent additionally validates `authToken` against its
+     * BACKEND_URL — proving the full auth flow (not just that it's reachable).
+     */
+    deep?: boolean;
+    /** StackFactor session token used for the deep backend-callback check. */
+    authToken?: string;
+    /** Call deadline; defaults to 15s (a health probe should be quick). */
+    deadlineMs?: number;
+}
+export interface AgentHealth {
+    /** The agent answered (and, for a deep check, auth succeeded). */
+    ok: boolean;
+    /** Deep check only: the agent reached the StackFactor backend (BACKEND_URL). */
+    backendReachable: boolean;
+    /** Agent build/version string, when the agent reports one. */
+    version: string;
+    /** Human-readable detail — carries the failure reason when `ok` is false. */
+    message: string;
+}
+/**
+ * Probes a deployed agent's `Agent.HealthCheck` (unary). Resolves with the
+ * agent's health; rejects on transport/ingress errors (e.g. gRPC UNIMPLEMENTED
+ * when the agent predates this RPC — callers should treat that as "redeploy to
+ * enable", not "down").
+ *
+ * @param agentUrl - The agent's Cloud Run URL (https://…run.app).
+ */
+export declare const checkAgent: (agentUrl: string, options?: CheckAgentOptions) => Promise<AgentHealth>;
 //# sourceMappingURL=client.d.ts.map

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"}
+{"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"}

package/dist/esm/client.js

@@ -92,3 +92,40 @@ export const callAgent = (agentUrl, request, options = {}) => new Promise((resol
     stream.on("error", (error) => settle(() => reject(error)));
     stream.on("end", () => settle(() => reject(new Error("Agent stream ended without a result or error"))));
 });
+const DEFAULT_HEALTH_DEADLINE_MS = 15_000;
+/**
+ * Probes a deployed agent's `Agent.HealthCheck` (unary). Resolves with the
+ * agent's health; rejects on transport/ingress errors (e.g. gRPC UNIMPLEMENTED
+ * when the agent predates this RPC — callers should treat that as "redeploy to
+ * enable", not "down").
+ *
+ * @param agentUrl - The agent's Cloud Run URL (https://…run.app).
+ */
+export const checkAgent = (agentUrl, options = {}) => new Promise((resolve, reject) => {
+    const loaded = loadAgentPackage();
+    const url = new URL(agentUrl);
+    const address = `${url.hostname}:${url.port || "443"}`;
+    const client = new loaded.stackfactor.agent.v1.Agent(address, buildCredentials(options.idToken));
+    const request = {
+        request_json: JSON.stringify({ authToken: options.authToken }),
+        deep: !!options.deep,
+    };
+    client.HealthCheck(request, { deadline: Date.now() + (options.deadlineMs ?? DEFAULT_HEALTH_DEADLINE_MS) }, (error, response) => {
+        try {
+            client.close();
+        }
+        catch {
+            // ignore close errors
+        }
+        if (error) {
+            reject(error);
+            return;
+        }
+        resolve({
+            ok: !!response?.ok,
+            backendReachable: !!response?.backend_reachable,
+            version: response?.version ?? "",
+            message: response?.message ?? "",
+        });
+    });
+});

package/dist/esm/index.d.ts

@@ -3,7 +3,7 @@ import errorHandling from "./errorHandling.js";
 import langChain from "./langChain.js";
 import logger from "./logger.js";
 import { serve } from "./serve.js";
-import { callAgent } from "./client.js";
+import { callAgent, checkAgent } from "./client.js";
 import * as runtimeContext from "./runtimeContext.js";
 export { constants };
 export { errorHandling };
@@ -11,6 +11,7 @@ export { langChain };
 export { logger };
 export { serve };
 export { callAgent };
-export type { AgentExecuteRequest, CallAgentOptions } from "./client.js";
+export { checkAgent };
+export type { AgentExecuteRequest, CallAgentOptions, CheckAgentOptions, AgentHealth, } from "./client.js";
 export { runtimeContext };
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,MAAM,oBAAoB,CAAC;AAC/C,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEzE,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,MAAM,oBAAoB,CAAC;AAC/C,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/esm/index.js

@@ -3,7 +3,7 @@ import errorHandling from "./errorHandling.js";
 import langChain from "./langChain.js";
 import logger from "./logger.js";
 import { serve } from "./serve.js";
-import { callAgent } from "./client.js";
+import { callAgent, checkAgent } from "./client.js";
 import * as runtimeContext from "./runtimeContext.js";
 export { constants };
 export { errorHandling };
@@ -11,4 +11,5 @@ export { langChain };
 export { logger };
 export { serve };
 export { callAgent };
+export { checkAgent };
 export { runtimeContext };

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,MAsGxE,CAAC"}
+{"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"}

package/dist/esm/serve.js

@@ -127,8 +127,32 @@ export const serve = (main, options = {}) => {
         };
         void handle();
     };
+    // Health probe served by the base server — agents get it for free.
+    //  - shallow: confirms the process is up and ingress auth works (the caller
+    //    reached this handler at all).
+    //  - deep: additionally runs the same `authenticate` path Execute uses, which
+    //    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, {
+            ok,
+            backend_reachable: backendReachable,
+            version: process.env.AGENT_VERSION ?? "",
+            message,
+        });
+        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"));
+    };
     const server = new grpc.Server();
-    server.addService(loadAgentService(), { Execute: execute });
+    server.addService(loadAgentService(), {
+        Execute: execute,
+        HealthCheck: healthCheck,
+    });
     // Insecure: Cloud Run terminates TLS at the edge and forwards h2c to the
     // container (requires the service to be deployed with --use-http2).
     server.bindAsync(`${host}:${port}`, grpc.ServerCredentials.createInsecure(), (err, boundPort) => {

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -46,7 +46,7 @@
     "@langchain/google-genai": "^2.1.26",
     "@langchain/openai": "^1.3.0",
     "@opentelemetry/api": "^1.9.0",
-    "@stackfactor/client-api": "^1.1.239",
+    "@stackfactor/client-api": "^1.1.241",
     "langchain": "^1.2.35",
     "mongoose": "^9.3.1",
     "openai": "^6.32.0",