@stackfactor/agent-utils 1.0.24 → 1.1.0

package/dist/cjs/index.d.ts

@@ -2,8 +2,12 @@ import constants from "./const.js";
 import errorHandling from "./errorHandling.js";
 import langChain from "./langChain.js";
 import logger from "./logger.js";
+import { serve } from "./serve.js";
+import * as runtimeContext from "./runtimeContext.js";
 export { constants };
 export { errorHandling };
 export { langChain };
 export { logger };
+export { serve };
+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;AAEjC,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,MAAM,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,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,cAAc,EAAE,CAAC"}

package/dist/cjs/index.js

@@ -1,9 +1,42 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.logger = exports.langChain = exports.errorHandling = exports.constants = void 0;
+exports.runtimeContext = 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"));
@@ -12,3 +45,7 @@ const langChain_js_1 = __importDefault(require("./langChain.js"));
 exports.langChain = langChain_js_1.default;
 const logger_js_1 = __importDefault(require("./logger.js"));
 exports.logger = logger_js_1.default;
+const serve_js_1 = require("./serve.js");
+Object.defineProperty(exports, "serve", { enumerable: true, get: function () { return serve_js_1.serve; } });
+const runtimeContext = __importStar(require("./runtimeContext.js"));
+exports.runtimeContext = runtimeContext;

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

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":";0CAgD6C,GAAG,KAAG,IAAI;wBAke/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBAyBG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,KAC1B,OAAO,CAAC,GAAG,CAAC;oCAuXF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,KACX,OAAO,CAAC,GAAG,CAAC;sDA6rBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CA59B8B,GAAG,KAAG,MAAM;mCAoBxC,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAigCT,wBAQE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":";0CAiD6C,GAAG,KAAG,IAAI;wBAke/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBAyBG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,KAC1B,OAAO,CAAC,GAAG,CAAC;oCAuXF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,KACX,OAAO,CAAC,GAAG,CAAC;sDAwsBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CAv+B8B,GAAG,KAAG,MAAM;mCAoBxC,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AA4gCT,wBAQE"}

package/dist/cjs/langChain.js

@@ -13,6 +13,7 @@ const langchain_1 = require("langchain");
 const errorHandling_js_1 = __importDefault(require("./errorHandling.js"));
 const logger_js_1 = __importDefault(require("./logger.js"));
 const zod_to_json_schema_1 = require("zod-to-json-schema");
+const runtimeContext_js_1 = require("./runtimeContext.js");
 const JSON_ESCAPE_INSTRUCTION = `
 CRITICAL - Your response must be valid JSON. Escape ALL special characters in string values:
 - Newlines → \\n
@@ -1001,8 +1002,16 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 streamUsage = { input_tokens: 0, output_tokens: 0 };
                 try {
                     assertQuotaAvailable();
-                    const stream = await llm.stream(activeMessages);
+                    // Honour caller cancellation: passing the signal tears down the
+                    // upstream HTTP request so a cancelled call stops billing tokens.
+                    const abortSignal = (0, runtimeContext_js_1.getAbortSignal)();
+                    const stream = await llm.stream(activeMessages, {
+                        signal: abortSignal ?? undefined,
+                    });
                     for await (const chunk of stream) {
+                        if (abortSignal?.aborted) {
+                            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") {

package/dist/cjs/runtimeContext.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Per-request execution context for an agent invocation.
+ *
+ * Agents read `config`, `params`, `onProgress`, `request`, and `event` as
+ * globals (the historical VM-host contract). When agents run as a long-lived
+ * gRPC server (see {@link "./serve"}), a single process handles many concurrent
+ * requests, so a shared mutable global would let requests clobber each other.
+ * This module stores the context per async call-chain via {@link AsyncLocalStorage}
+ * and exposes the same names as global getters, keeping the agent programming
+ * model intact while being concurrency-safe.
+ */
+export interface RequestContext {
+    config: any;
+    params: any;
+    request: any;
+    event: any;
+    onProgress: ((update: {
+        progress: number;
+        message: string;
+    }) => void) | null;
+    /** Aborted when the caller cancels (e.g. the frontend socket dropped). */
+    signal: AbortSignal | null;
+    /** Identity + tenant resolved from the request's auth token (see serve). */
+    session?: {
+        user: any;
+        tenant: any;
+    } | null;
+}
+/** Run `fn` with `ctx` bound as the active request context. */
+export declare const runWithContext: <T>(ctx: RequestContext, fn: () => Promise<T>) => Promise<T>;
+/** The active request context, or `undefined` outside a request. */
+export declare const getContext: () => RequestContext | undefined;
+/** The active request's abort signal, or `null`. */
+export declare const getAbortSignal: () => AbortSignal | null;
+/**
+ * Install global getters (`config`, `params`, `onProgress`, `request`, `event`)
+ * that resolve to the active {@link RequestContext}. Idempotent; call once at
+ * startup. After this, agent code referencing those globals transparently reads
+ * the current request's values even under concurrency.
+ */
+export declare const installGlobals: () => void;
+//# sourceMappingURL=runtimeContext.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeContext.d.ts","sourceRoot":"","sources":["../../src/runtimeContext.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,GAAG,CAAC;IACZ,MAAM,EAAE,GAAG,CAAC;IACZ,OAAO,EAAE,GAAG,CAAC;IACb,KAAK,EAAE,GAAG,CAAC;IACX,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7E,0EAA0E;IAC1E,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,4EAA4E;IAC5E,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,GAAG,CAAC;QAAC,MAAM,EAAE,GAAG,CAAA;KAAE,GAAG,IAAI,CAAC;CAC7C;AAID,+DAA+D;AAC/D,eAAO,MAAM,cAAc,GAAI,CAAC,EAC9B,KAAK,cAAc,EACnB,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAyB,CAAC;AAEtC,oEAAoE;AACpE,eAAO,MAAM,UAAU,QAAO,cAAc,GAAG,SAA+B,CAAC;AAE/E,oDAAoD;AACpD,eAAO,MAAM,cAAc,QAAO,WAAW,GAAG,IACZ,CAAC;AAIrC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAO,IAUjC,CAAC"}

package/dist/cjs/runtimeContext.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installGlobals = exports.getAbortSignal = exports.getContext = exports.runWithContext = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+const storage = new node_async_hooks_1.AsyncLocalStorage();
+/** Run `fn` with `ctx` bound as the active request context. */
+const runWithContext = (ctx, fn) => storage.run(ctx, fn);
+exports.runWithContext = runWithContext;
+/** The active request context, or `undefined` outside a request. */
+const getContext = () => storage.getStore();
+exports.getContext = getContext;
+/** The active request's abort signal, or `null`. */
+const getAbortSignal = () => storage.getStore()?.signal ?? null;
+exports.getAbortSignal = getAbortSignal;
+let installed = false;
+/**
+ * Install global getters (`config`, `params`, `onProgress`, `request`, `event`)
+ * that resolve to the active {@link RequestContext}. Idempotent; call once at
+ * startup. After this, agent code referencing those globals transparently reads
+ * the current request's values even under concurrency.
+ */
+const installGlobals = () => {
+    if (installed)
+        return;
+    installed = true;
+    const define = (name, get) => Object.defineProperty(globalThis, name, { get, configurable: true });
+    define("config", () => storage.getStore()?.config);
+    define("params", () => storage.getStore()?.params);
+    define("request", () => storage.getStore()?.request);
+    define("event", () => storage.getStore()?.event);
+    define("onProgress", () => storage.getStore()?.onProgress);
+};
+exports.installGlobals = installGlobals;

package/dist/cjs/serve.d.ts

@@ -0,0 +1,38 @@
+import * as grpc from "@grpc/grpc-js";
+/**
+ * The agent entry point. Reads `params` / `config` / `onProgress` from globals
+ * (populated per-request by {@link serve}) and returns the structured result.
+ * Receives the request's {@link AbortSignal} for cooperative cancellation; most
+ * agents can ignore it since the LLM layer honours it automatically.
+ */
+export type AgentMain = (signal?: AbortSignal) => Promise<any>;
+/**
+ * Resolves the caller's identity + tenant from the request, or throws to refuse
+ * the call. The default validates `request.authToken` against the StackFactor
+ * API via `client-api`'s `session.getSession`.
+ */
+export type Authenticator = (request: any) => Promise<{
+    user: any;
+    tenant: any;
+}>;
+export interface ServeOptions {
+    /** Port to bind. Defaults to `process.env.PORT` then `8080` (Cloud Run). */
+    port?: number;
+    /** Host to bind. Defaults to `0.0.0.0`. */
+    host?: string;
+    /** Override the auth check (e.g. in tests). Defaults to {@link defaultAuthenticate}. */
+    authenticate?: Authenticator;
+}
+/**
+ * Start a gRPC server that exposes `main` as the fleet-standard `Agent.Execute`
+ * RPC. Per request it binds a {@link RequestContext} (so the agent's globals are
+ * concurrency-safe), streams each `onProgress` event as a `Progress` frame, and
+ * sends a final `Result` or `Error`. Caller cancellation (e.g. the frontend
+ * socket dropping) aborts the in-flight LLM call to stop billing.
+ *
+ * @example
+ *   const { serve } = require("@stackfactor/agent-utils");
+ *   serve(require("./src/main"));
+ */
+export declare const serve: (main: AgentMain, options?: ServeOptions) => grpc.Server;
+//# sourceMappingURL=serve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AAStC;;;;;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;AAqGD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAAI,MAAM,SAAS,EAAE,UAAS,YAAiB,KAAG,IAAI,CAAC,MAsGxE,CAAC"}

package/dist/cjs/serve.js

@@ -0,0 +1,234 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serve = void 0;
+const grpc = __importStar(require("@grpc/grpc-js"));
+const protoLoader = __importStar(require("@grpc/proto-loader"));
+const client_api_1 = require("@stackfactor/client-api");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const logger_js_1 = __importDefault(require("./logger.js"));
+const runtimeContext_js_1 = require("./runtimeContext.js");
+/** Marks an auth failure so the handler can map it to gRPC UNAUTHENTICATED. */
+class UnauthenticatedError extends Error {
+}
+/**
+ * Default authenticator: require a token on the request and resolve it to a
+ * session via the StackFactor API. Requires `BACKEND_URL` (or `REACT_APP_NODE_ENV`)
+ * to point client-api at the right backend. Throws {@link UnauthenticatedError}
+ * when the token is missing or rejected.
+ */
+const defaultAuthenticate = async (request) => {
+    const token = request?.authToken ?? request?.authorization;
+    if (!token) {
+        throw new UnauthenticatedError("Missing auth token");
+    }
+    try {
+        return await client_api_1.session.getSession(token);
+    }
+    catch (error) {
+        throw new UnauthenticatedError(`Invalid auth token: ${error?.message ?? error}`);
+    }
+};
+/**
+ * gRPC contract shared by the entire agent fleet. `data`/`config`/`request` are
+ * carried as JSON strings so arbitrary payloads need no proto schema churn.
+ * `Execute` is server-streaming: zero or more `Progress` frames (driven by the
+ * agent's `onProgress`) followed by exactly one `Result` or `Error`.
+ */
+const PROTO = `
+syntax = "proto3";
+package stackfactor.agent.v1;
+
+service Agent {
+  rpc Execute(ExecuteRequest) returns (stream Update);
+}
+
+message ExecuteRequest {
+  string content_type = 1;
+  string data_json    = 2;
+  string config_json  = 3;
+  string request_json = 4;
+  int32  event        = 5;
+}
+
+message Update {
+  oneof payload {
+    Progress  progress = 1;
+    Result    result   = 2;
+    ErrorInfo error    = 3;
+  }
+}
+
+message Progress  { int32 progress = 1; string message = 2; }
+message Result    { string result_json = 1; }
+message ErrorInfo { int32 code = 1; string message = 2; }
+`;
+const loadAgentService = () => {
+    // proto-loader reads from a file; write the embedded schema to a temp path so
+    // the package stays self-contained across the cjs/esm dual build.
+    const file = (0, node_path_1.join)((0, node_os_1.tmpdir)(), "stackfactor-agent.v1.proto");
+    (0, node_fs_1.writeFileSync)(file, PROTO);
+    const packageDefinition = protoLoader.loadSync(file, {
+        keepCase: true,
+        longs: String,
+        enums: String,
+        defaults: true,
+        oneofs: true,
+    });
+    const loaded = grpc.loadPackageDefinition(packageDefinition);
+    return loaded.stackfactor.agent.v1.Agent.service;
+};
+const safeParse = (value, fallback) => {
+    if (!value)
+        return fallback;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+};
+/**
+ * Agents that fail throw `new Error(JSON.stringify({ code, message }))`. Unwrap
+ * that back into a structured gRPC error frame; fall back to a 500 otherwise.
+ */
+const toErrorFrame = (error) => {
+    try {
+        const parsed = JSON.parse(error?.message);
+        if (parsed && typeof parsed.code === "number") {
+            return { code: parsed.code, message: String(parsed.message ?? "") };
+        }
+    }
+    catch {
+        // not a structured error
+    }
+    return { code: 500, message: String(error?.message ?? error) };
+};
+/**
+ * Start a gRPC server that exposes `main` as the fleet-standard `Agent.Execute`
+ * RPC. Per request it binds a {@link RequestContext} (so the agent's globals are
+ * concurrency-safe), streams each `onProgress` event as a `Progress` frame, and
+ * sends a final `Result` or `Error`. Caller cancellation (e.g. the frontend
+ * socket dropping) aborts the in-flight LLM call to stop billing.
+ *
+ * @example
+ *   const { serve } = require("@stackfactor/agent-utils");
+ *   serve(require("./src/main"));
+ */
+const serve = (main, options = {}) => {
+    (0, runtimeContext_js_1.installGlobals)();
+    const port = options.port ?? (Number(process.env.PORT) || 8080);
+    const host = options.host ?? "0.0.0.0";
+    const authenticate = options.authenticate ?? defaultAuthenticate;
+    const execute = (call) => {
+        const abort = new AbortController();
+        call.on("cancelled", () => abort.abort());
+        call.on("error", () => abort.abort());
+        const req = call.request ?? {};
+        const request = safeParse(req.request_json, {});
+        const onProgress = (update) => {
+            if (abort.signal.aborted)
+                return;
+            call.write({
+                progress: {
+                    progress: Math.round(update?.progress ?? 0),
+                    message: update?.message ?? "",
+                },
+            });
+        };
+        const handle = async () => {
+            // Authenticate first — refuse the call when the token is missing/invalid.
+            let session;
+            try {
+                session = await authenticate(request);
+            }
+            catch (error) {
+                const message = error?.message ?? "Unauthenticated";
+                logger_js_1.default.log(null, logger_js_1.default.levels.warn, `agent Execute refused: ${message}`);
+                call.emit("error", {
+                    code: grpc.status.UNAUTHENTICATED,
+                    details: message,
+                });
+                return;
+            }
+            const context = {
+                config: safeParse(req.config_json, {}),
+                params: {
+                    contentType: req.content_type,
+                    data: safeParse(req.data_json, {}),
+                },
+                request: { ...request, session }, // expose identity/tenant to the agent
+                event: req.event ?? 0,
+                onProgress,
+                signal: abort.signal,
+                session,
+            };
+            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) } });
+                }
+            }
+            catch (error) {
+                if (!abort.signal.aborted) {
+                    logger_js_1.default.log(null, logger_js_1.default.levels.error, `agent Execute failed: ${error?.message ?? error}`);
+                    call.write({ error: toErrorFrame(error) });
+                }
+            }
+            finally {
+                call.end();
+            }
+        };
+        void handle();
+    };
+    const server = new grpc.Server();
+    server.addService(loadAgentService(), { Execute: execute });
+    // 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) => {
+        if (err) {
+            logger_js_1.default.log(null, logger_js_1.default.levels.error, `agent gRPC server failed to bind ${host}:${port}: ${err.message}`);
+            throw err;
+        }
+        logger_js_1.default.log(null, logger_js_1.default.levels.info, `agent gRPC server listening on ${host}:${boundPort}`);
+    });
+    return server;
+};
+exports.serve = serve;

package/dist/esm/index.d.ts

@@ -2,8 +2,12 @@ import constants from "./const.js";
 import errorHandling from "./errorHandling.js";
 import langChain from "./langChain.js";
 import logger from "./logger.js";
+import { serve } from "./serve.js";
+import * as runtimeContext from "./runtimeContext.js";
 export { constants };
 export { errorHandling };
 export { langChain };
 export { logger };
+export { serve };
+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;AAEjC,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,MAAM,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,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,cAAc,EAAE,CAAC"}

package/dist/esm/index.js

@@ -2,7 +2,11 @@ import constants from "./const.js";
 import errorHandling from "./errorHandling.js";
 import langChain from "./langChain.js";
 import logger from "./logger.js";
+import { serve } from "./serve.js";
+import * as runtimeContext from "./runtimeContext.js";
 export { constants };
 export { errorHandling };
 export { langChain };
 export { logger };
+export { serve };
+export { runtimeContext };

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

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":";0CAgD6C,GAAG,KAAG,IAAI;wBAke/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBAyBG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,KAC1B,OAAO,CAAC,GAAG,CAAC;oCAuXF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,KACX,OAAO,CAAC,GAAG,CAAC;sDA6rBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CA59B8B,GAAG,KAAG,MAAM;mCAoBxC,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAigCT,wBAQE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":";0CAiD6C,GAAG,KAAG,IAAI;wBAke/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBAyBG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,KAC1B,OAAO,CAAC,GAAG,CAAC;oCAuXF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,KACX,OAAO,CAAC,GAAG,CAAC;sDAwsBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CAv+B8B,GAAG,KAAG,MAAM;mCAoBxC,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AA4gCT,wBAQE"}

package/dist/esm/langChain.js

@@ -8,6 +8,7 @@ import { createAgent as createLangChainAgent } from "langchain";
 import errorHandlingHelper from "./errorHandling.js";
 import logger from "./logger.js";
 import { zodToJsonSchema } from "zod-to-json-schema";
+import { getAbortSignal } from "./runtimeContext.js";
 const JSON_ESCAPE_INSTRUCTION = `
 CRITICAL - Your response must be valid JSON. Escape ALL special characters in string values:
 - Newlines → \\n
@@ -996,8 +997,16 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 streamUsage = { input_tokens: 0, output_tokens: 0 };
                 try {
                     assertQuotaAvailable();
-                    const stream = await llm.stream(activeMessages);
+                    // Honour caller cancellation: passing the signal tears down the
+                    // upstream HTTP request so a cancelled call stops billing tokens.
+                    const abortSignal = getAbortSignal();
+                    const stream = await llm.stream(activeMessages, {
+                        signal: abortSignal ?? undefined,
+                    });
                     for await (const chunk of stream) {
+                        if (abortSignal?.aborted) {
+                            throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, "Request cancelled by caller");
+                        }
                         accumulateChunkUsage(streamUsage, chunk);
                         const content = chunk?.content || chunk;
                         if (typeof content === "string") {

package/dist/esm/runtimeContext.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Per-request execution context for an agent invocation.
+ *
+ * Agents read `config`, `params`, `onProgress`, `request`, and `event` as
+ * globals (the historical VM-host contract). When agents run as a long-lived
+ * gRPC server (see {@link "./serve"}), a single process handles many concurrent
+ * requests, so a shared mutable global would let requests clobber each other.
+ * This module stores the context per async call-chain via {@link AsyncLocalStorage}
+ * and exposes the same names as global getters, keeping the agent programming
+ * model intact while being concurrency-safe.
+ */
+export interface RequestContext {
+    config: any;
+    params: any;
+    request: any;
+    event: any;
+    onProgress: ((update: {
+        progress: number;
+        message: string;
+    }) => void) | null;
+    /** Aborted when the caller cancels (e.g. the frontend socket dropped). */
+    signal: AbortSignal | null;
+    /** Identity + tenant resolved from the request's auth token (see serve). */
+    session?: {
+        user: any;
+        tenant: any;
+    } | null;
+}
+/** Run `fn` with `ctx` bound as the active request context. */
+export declare const runWithContext: <T>(ctx: RequestContext, fn: () => Promise<T>) => Promise<T>;
+/** The active request context, or `undefined` outside a request. */
+export declare const getContext: () => RequestContext | undefined;
+/** The active request's abort signal, or `null`. */
+export declare const getAbortSignal: () => AbortSignal | null;
+/**
+ * Install global getters (`config`, `params`, `onProgress`, `request`, `event`)
+ * that resolve to the active {@link RequestContext}. Idempotent; call once at
+ * startup. After this, agent code referencing those globals transparently reads
+ * the current request's values even under concurrency.
+ */
+export declare const installGlobals: () => void;
+//# sourceMappingURL=runtimeContext.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeContext.d.ts","sourceRoot":"","sources":["../../src/runtimeContext.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,GAAG,CAAC;IACZ,MAAM,EAAE,GAAG,CAAC;IACZ,OAAO,EAAE,GAAG,CAAC;IACb,KAAK,EAAE,GAAG,CAAC;IACX,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7E,0EAA0E;IAC1E,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,4EAA4E;IAC5E,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,GAAG,CAAC;QAAC,MAAM,EAAE,GAAG,CAAA;KAAE,GAAG,IAAI,CAAC;CAC7C;AAID,+DAA+D;AAC/D,eAAO,MAAM,cAAc,GAAI,CAAC,EAC9B,KAAK,cAAc,EACnB,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAyB,CAAC;AAEtC,oEAAoE;AACpE,eAAO,MAAM,UAAU,QAAO,cAAc,GAAG,SAA+B,CAAC;AAE/E,oDAAoD;AACpD,eAAO,MAAM,cAAc,QAAO,WAAW,GAAG,IACZ,CAAC;AAIrC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAO,IAUjC,CAAC"}

package/dist/esm/runtimeContext.js

@@ -0,0 +1,26 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+/** Run `fn` with `ctx` bound as the active request context. */
+export const runWithContext = (ctx, fn) => storage.run(ctx, fn);
+/** The active request context, or `undefined` outside a request. */
+export const getContext = () => storage.getStore();
+/** The active request's abort signal, or `null`. */
+export const getAbortSignal = () => storage.getStore()?.signal ?? null;
+let installed = false;
+/**
+ * Install global getters (`config`, `params`, `onProgress`, `request`, `event`)
+ * that resolve to the active {@link RequestContext}. Idempotent; call once at
+ * startup. After this, agent code referencing those globals transparently reads
+ * the current request's values even under concurrency.
+ */
+export const installGlobals = () => {
+    if (installed)
+        return;
+    installed = true;
+    const define = (name, get) => Object.defineProperty(globalThis, name, { get, configurable: true });
+    define("config", () => storage.getStore()?.config);
+    define("params", () => storage.getStore()?.params);
+    define("request", () => storage.getStore()?.request);
+    define("event", () => storage.getStore()?.event);
+    define("onProgress", () => storage.getStore()?.onProgress);
+};

package/dist/esm/serve.d.ts

@@ -0,0 +1,38 @@
+import * as grpc from "@grpc/grpc-js";
+/**
+ * The agent entry point. Reads `params` / `config` / `onProgress` from globals
+ * (populated per-request by {@link serve}) and returns the structured result.
+ * Receives the request's {@link AbortSignal} for cooperative cancellation; most
+ * agents can ignore it since the LLM layer honours it automatically.
+ */
+export type AgentMain = (signal?: AbortSignal) => Promise<any>;
+/**
+ * Resolves the caller's identity + tenant from the request, or throws to refuse
+ * the call. The default validates `request.authToken` against the StackFactor
+ * API via `client-api`'s `session.getSession`.
+ */
+export type Authenticator = (request: any) => Promise<{
+    user: any;
+    tenant: any;
+}>;
+export interface ServeOptions {
+    /** Port to bind. Defaults to `process.env.PORT` then `8080` (Cloud Run). */
+    port?: number;
+    /** Host to bind. Defaults to `0.0.0.0`. */
+    host?: string;
+    /** Override the auth check (e.g. in tests). Defaults to {@link defaultAuthenticate}. */
+    authenticate?: Authenticator;
+}
+/**
+ * Start a gRPC server that exposes `main` as the fleet-standard `Agent.Execute`
+ * RPC. Per request it binds a {@link RequestContext} (so the agent's globals are
+ * concurrency-safe), streams each `onProgress` event as a `Progress` frame, and
+ * sends a final `Result` or `Error`. Caller cancellation (e.g. the frontend
+ * socket dropping) aborts the in-flight LLM call to stop billing.
+ *
+ * @example
+ *   const { serve } = require("@stackfactor/agent-utils");
+ *   serve(require("./src/main"));
+ */
+export declare const serve: (main: AgentMain, options?: ServeOptions) => grpc.Server;
+//# sourceMappingURL=serve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AAStC;;;;;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;AAqGD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAAI,MAAM,SAAS,EAAE,UAAS,YAAiB,KAAG,IAAI,CAAC,MAsGxE,CAAC"}

package/dist/esm/serve.js

@@ -0,0 +1,194 @@
+import * as grpc from "@grpc/grpc-js";
+import * as protoLoader from "@grpc/proto-loader";
+import { session as clientSession } from "@stackfactor/client-api";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import logger from "./logger.js";
+import { runWithContext, installGlobals } from "./runtimeContext.js";
+/** Marks an auth failure so the handler can map it to gRPC UNAUTHENTICATED. */
+class UnauthenticatedError extends Error {
+}
+/**
+ * Default authenticator: require a token on the request and resolve it to a
+ * session via the StackFactor API. Requires `BACKEND_URL` (or `REACT_APP_NODE_ENV`)
+ * to point client-api at the right backend. Throws {@link UnauthenticatedError}
+ * when the token is missing or rejected.
+ */
+const defaultAuthenticate = async (request) => {
+    const token = request?.authToken ?? request?.authorization;
+    if (!token) {
+        throw new UnauthenticatedError("Missing auth token");
+    }
+    try {
+        return await clientSession.getSession(token);
+    }
+    catch (error) {
+        throw new UnauthenticatedError(`Invalid auth token: ${error?.message ?? error}`);
+    }
+};
+/**
+ * gRPC contract shared by the entire agent fleet. `data`/`config`/`request` are
+ * carried as JSON strings so arbitrary payloads need no proto schema churn.
+ * `Execute` is server-streaming: zero or more `Progress` frames (driven by the
+ * agent's `onProgress`) followed by exactly one `Result` or `Error`.
+ */
+const PROTO = `
+syntax = "proto3";
+package stackfactor.agent.v1;
+
+service Agent {
+  rpc Execute(ExecuteRequest) returns (stream Update);
+}
+
+message ExecuteRequest {
+  string content_type = 1;
+  string data_json    = 2;
+  string config_json  = 3;
+  string request_json = 4;
+  int32  event        = 5;
+}
+
+message Update {
+  oneof payload {
+    Progress  progress = 1;
+    Result    result   = 2;
+    ErrorInfo error    = 3;
+  }
+}
+
+message Progress  { int32 progress = 1; string message = 2; }
+message Result    { string result_json = 1; }
+message ErrorInfo { int32 code = 1; string message = 2; }
+`;
+const loadAgentService = () => {
+    // proto-loader reads from a file; write the embedded schema to a temp path so
+    // the package stays self-contained across the cjs/esm dual build.
+    const file = join(tmpdir(), "stackfactor-agent.v1.proto");
+    writeFileSync(file, PROTO);
+    const packageDefinition = protoLoader.loadSync(file, {
+        keepCase: true,
+        longs: String,
+        enums: String,
+        defaults: true,
+        oneofs: true,
+    });
+    const loaded = grpc.loadPackageDefinition(packageDefinition);
+    return loaded.stackfactor.agent.v1.Agent.service;
+};
+const safeParse = (value, fallback) => {
+    if (!value)
+        return fallback;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+};
+/**
+ * Agents that fail throw `new Error(JSON.stringify({ code, message }))`. Unwrap
+ * that back into a structured gRPC error frame; fall back to a 500 otherwise.
+ */
+const toErrorFrame = (error) => {
+    try {
+        const parsed = JSON.parse(error?.message);
+        if (parsed && typeof parsed.code === "number") {
+            return { code: parsed.code, message: String(parsed.message ?? "") };
+        }
+    }
+    catch {
+        // not a structured error
+    }
+    return { code: 500, message: String(error?.message ?? error) };
+};
+/**
+ * Start a gRPC server that exposes `main` as the fleet-standard `Agent.Execute`
+ * RPC. Per request it binds a {@link RequestContext} (so the agent's globals are
+ * concurrency-safe), streams each `onProgress` event as a `Progress` frame, and
+ * sends a final `Result` or `Error`. Caller cancellation (e.g. the frontend
+ * socket dropping) aborts the in-flight LLM call to stop billing.
+ *
+ * @example
+ *   const { serve } = require("@stackfactor/agent-utils");
+ *   serve(require("./src/main"));
+ */
+export const serve = (main, options = {}) => {
+    installGlobals();
+    const port = options.port ?? (Number(process.env.PORT) || 8080);
+    const host = options.host ?? "0.0.0.0";
+    const authenticate = options.authenticate ?? defaultAuthenticate;
+    const execute = (call) => {
+        const abort = new AbortController();
+        call.on("cancelled", () => abort.abort());
+        call.on("error", () => abort.abort());
+        const req = call.request ?? {};
+        const request = safeParse(req.request_json, {});
+        const onProgress = (update) => {
+            if (abort.signal.aborted)
+                return;
+            call.write({
+                progress: {
+                    progress: Math.round(update?.progress ?? 0),
+                    message: update?.message ?? "",
+                },
+            });
+        };
+        const handle = async () => {
+            // Authenticate first — refuse the call when the token is missing/invalid.
+            let session;
+            try {
+                session = await authenticate(request);
+            }
+            catch (error) {
+                const message = error?.message ?? "Unauthenticated";
+                logger.log(null, logger.levels.warn, `agent Execute refused: ${message}`);
+                call.emit("error", {
+                    code: grpc.status.UNAUTHENTICATED,
+                    details: message,
+                });
+                return;
+            }
+            const context = {
+                config: safeParse(req.config_json, {}),
+                params: {
+                    contentType: req.content_type,
+                    data: safeParse(req.data_json, {}),
+                },
+                request: { ...request, session }, // expose identity/tenant to the agent
+                event: req.event ?? 0,
+                onProgress,
+                signal: abort.signal,
+                session,
+            };
+            try {
+                const result = await runWithContext(context, () => main(abort.signal));
+                if (!abort.signal.aborted) {
+                    call.write({ result: { result_json: JSON.stringify(result ?? null) } });
+                }
+            }
+            catch (error) {
+                if (!abort.signal.aborted) {
+                    logger.log(null, logger.levels.error, `agent Execute failed: ${error?.message ?? error}`);
+                    call.write({ error: toErrorFrame(error) });
+                }
+            }
+            finally {
+                call.end();
+            }
+        };
+        void handle();
+    };
+    const server = new grpc.Server();
+    server.addService(loadAgentService(), { Execute: execute });
+    // 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) => {
+        if (err) {
+            logger.log(null, logger.levels.error, `agent gRPC server failed to bind ${host}:${port}: ${err.message}`);
+            throw err;
+        }
+        logger.log(null, logger.levels.info, `agent gRPC server listening on ${host}:${boundPort}`);
+    });
+    return server;
+};

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "restricted"
   },
-  "version": "1.0.24",
+  "version": "1.1.0",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -40,10 +40,13 @@
   "homepage": "https://github.com/StackFactor/stackfactor-agent-utils#readme",
   "dependencies": {
     "@google/genai": "^1.46.0",
+    "@grpc/grpc-js": "^1.14.4",
+    "@grpc/proto-loader": "^0.7.15",
     "@langchain/anthropic": "^1.3.25",
     "@langchain/google-genai": "^2.1.26",
     "@langchain/openai": "^1.3.0",
     "@opentelemetry/api": "^1.9.0",
+    "@stackfactor/client-api": "^1.1.239",
     "langchain": "^1.2.35",
     "mongoose": "^9.3.1",
     "openai": "^6.32.0",