@stackfactor/agent-utils 1.1.0 → 1.1.2

package/dist/cjs/agentProto.d.ts

@@ -0,0 +1,19 @@
+import * as grpc from "@grpc/grpc-js";
+/**
+ * gRPC contract shared by the entire agent fleet — the `serve()` server AND the
+ * relay client. `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`.
+ */
+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";
+/**
+ * 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
+ * cjs/esm dual build. Returns the loaded package (server uses
+ * `.stackfactor.agent.v1.Agent.service`; client uses the `Agent` constructor).
+ */
+export declare const loadAgentPackage: () => any;
+/** The Agent gRPC service definition (for the `serve()` server). */
+export declare const loadAgentService: () => grpc.ServiceDefinition;
+//# sourceMappingURL=agentProto.d.ts.map

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

@@ -0,0 +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"}

package/dist/cjs/agentProto.js

@@ -0,0 +1,98 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAgentService = exports.loadAgentPackage = exports.PROTO = void 0;
+const grpc = __importStar(require("@grpc/grpc-js"));
+const protoLoader = __importStar(require("@grpc/proto-loader"));
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+/**
+ * gRPC contract shared by the entire agent fleet — the `serve()` server AND the
+ * relay client. `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`.
+ */
+exports.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; }
+`;
+/**
+ * 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
+ * cjs/esm dual build. Returns the loaded package (server uses
+ * `.stackfactor.agent.v1.Agent.service`; client uses the `Agent` constructor).
+ */
+const loadAgentPackage = () => {
+    const file = (0, node_path_1.join)((0, node_os_1.tmpdir)(), "stackfactor-agent.v1.proto");
+    (0, node_fs_1.writeFileSync)(file, exports.PROTO);
+    const packageDefinition = protoLoader.loadSync(file, {
+        keepCase: true,
+        longs: String,
+        enums: String,
+        defaults: true,
+        oneofs: true,
+    });
+    return grpc.loadPackageDefinition(packageDefinition);
+};
+exports.loadAgentPackage = loadAgentPackage;
+/** The Agent gRPC service definition (for the `serve()` server). */
+const loadAgentService = () => (0, exports.loadAgentPackage)().stackfactor.agent.v1.Agent.service;
+exports.loadAgentService = loadAgentService;

package/dist/cjs/client.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The fleet `Agent.Execute` request. `*_json` fields are JSON strings.
+ * `request_json` MUST include the caller's StackFactor session token as
+ * `authToken` — the agent validates it (via `serve()`'s auth gate) before
+ * running. This is distinct from the Cloud Run ID token (see `CallAgentOptions`).
+ */
+export interface AgentExecuteRequest {
+    content_type: string;
+    data_json: string;
+    config_json: string;
+    request_json: string;
+    event: number;
+}
+export interface CallAgentOptions {
+    /**
+     * Google ID token (audience = the agent's Cloud Run URL) to get past Cloud
+     * Run's `--no-allow-unauthenticated` ingress. Attached as `authorization:
+     * Bearer` metadata. The agent never sees it; ingress consumes it.
+     */
+    idToken?: string;
+    /** Called for each streamed `Progress` frame (e.g. to forward to a socket). */
+    onProgress?: (update: {
+        progress: number;
+        message: string;
+    }) => void;
+    /** Abort the RPC (e.g. the frontend socket dropped) → stops the agent's LLM. */
+    signal?: AbortSignal;
+    /** Call deadline; defaults to 900s to match Cloud Run's max request timeout. */
+    deadlineMs?: number;
+}
+/**
+ * Calls a deployed agent's `Agent.Execute` over gRPC server-streaming. Forwards
+ * each `Progress` frame to `onProgress`, resolves with the parsed `result_json`
+ * on `Result`, and rejects (with `error.code`) on `ErrorInfo`. Caller-cancel via
+ * `options.signal` cancels the RPC.
+ *
+ * @param agentUrl - The agent's Cloud Run URL (https://…run.app).
+ * @param request - The `ExecuteRequest` (its `request_json` carries `authToken`).
+ */
+export declare const callAgent: (agentUrl: string, request: AgentExecuteRequest, options?: CallAgentOptions) => Promise<any>;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +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"}

package/dist/cjs/client.js

@@ -0,0 +1,131 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callAgent = void 0;
+const grpc = __importStar(require("@grpc/grpc-js"));
+const agentProto_js_1 = require("./agentProto.js");
+const DEFAULT_DEADLINE_MS = 900_000;
+const safeParse = (value, fallback) => {
+    if (!value)
+        return fallback;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+};
+/** Turns an `ErrorInfo` frame into an Error carrying the agent's `code`. */
+const agentError = (frame) => {
+    const error = new Error(frame?.message || "Agent error");
+    error.code = frame?.code;
+    return error;
+};
+/**
+ * Channel credentials for an authenticated Cloud Run agent: TLS (Cloud Run
+ * terminates at the edge) plus per-call metadata carrying the ID token.
+ */
+const buildCredentials = (idToken) => {
+    const ssl = grpc.credentials.createSsl();
+    if (!idToken) {
+        return ssl;
+    }
+    const callCreds = grpc.credentials.createFromMetadataGenerator((_ctx, cb) => {
+        const metadata = new grpc.Metadata();
+        metadata.add("authorization", `Bearer ${idToken}`);
+        cb(null, metadata);
+    });
+    return grpc.credentials.combineChannelCredentials(ssl, callCreds);
+};
+/**
+ * Calls a deployed agent's `Agent.Execute` over gRPC server-streaming. Forwards
+ * each `Progress` frame to `onProgress`, resolves with the parsed `result_json`
+ * on `Result`, and rejects (with `error.code`) on `ErrorInfo`. Caller-cancel via
+ * `options.signal` cancels the RPC.
+ *
+ * @param agentUrl - The agent's Cloud Run URL (https://…run.app).
+ * @param request - The `ExecuteRequest` (its `request_json` carries `authToken`).
+ */
+const callAgent = (agentUrl, request, 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 stream = client.Execute(request, {
+        deadline: Date.now() + (options.deadlineMs ?? DEFAULT_DEADLINE_MS),
+    });
+    let settled = false;
+    const settle = (run) => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        try {
+            client.close();
+        }
+        catch {
+            // ignore close errors
+        }
+        run();
+    };
+    if (options.signal) {
+        if (options.signal.aborted) {
+            stream.cancel();
+        }
+        else {
+            options.signal.addEventListener("abort", () => stream.cancel(), {
+                once: true,
+            });
+        }
+    }
+    stream.on("data", (update) => {
+        if (update.progress) {
+            options.onProgress?.({
+                progress: update.progress.progress ?? 0,
+                message: update.progress.message ?? "",
+            });
+        }
+        else if (update.result) {
+            const result = safeParse(update.result.result_json, null);
+            settle(() => resolve(result));
+        }
+        else if (update.error) {
+            settle(() => reject(agentError(update.error)));
+        }
+    });
+    stream.on("error", (error) => settle(() => reject(error)));
+    stream.on("end", () => settle(() => reject(new Error("Agent stream ended without a result or error"))));
+});
+exports.callAgent = callAgent;

package/dist/cjs/index.d.ts

@@ -3,11 +3,14 @@ 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 * as runtimeContext from "./runtimeContext.js";
 export { constants };
 export { errorHandling };
 export { langChain };
 export { logger };
 export { serve };
+export { callAgent };
+export type { AgentExecuteRequest, CallAgentOptions } 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,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"}
+{"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"}

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.serve = exports.logger = exports.langChain = exports.errorHandling = exports.constants = void 0;
+exports.runtimeContext = 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"));
@@ -47,5 +47,7 @@ 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 client_js_1 = require("./client.js");
+Object.defineProperty(exports, "callAgent", { enumerable: true, get: function () { return client_js_1.callAgent; } });
 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":";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"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":";0CAiD6C,GAAG,KAAG,IAAI;wBAyhB/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;oCAqXF,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;sDAosBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CAn+B8B,GAAG,KAAG,MAAM;mCAoBxC,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAwgCT,wBAQE"}

package/dist/cjs/langChain.js

@@ -68,40 +68,81 @@ const recordCost = (cost) => {
     }
 };
 /**
- * Looks up the per-model pricing entry from `config.modelPricing`. Returns `null`
- * when pricing is not configured for the model, in which case cost recording
- * becomes a no-op (the call still succeeds — pricing data is the host's
- * responsibility, not the agent's).
+ * Reads a per-model rate from the flat cost constants the integration defines
+ * in its `config.yaml` (exposed on the config object), e.g.
+ * `claude-opus-4-7-input-token-costs`. Returns `null` when the constant is
+ * absent or not numeric, in which case cost recording becomes a no-op (the
+ * call still succeeds — pricing is the integration's configuration concern).
  */
-const getModelPrice = (modelName, config) => {
-    const pricing = config?.modelPricing;
-    if (!pricing)
+const getModelRate = (modelName, config, kind) => {
+    if (!config || !modelName)
         return null;
-    return pricing[modelName] || null;
+    const rate = Number(config[`${modelName}-${kind}-costs`]);
+    return Number.isFinite(rate) ? rate : null;
 };
 /**
- * Computes USD cost for a text LLM call. `config.modelPricing[modelName]` is
- * expected to provide `input` and `output` rates in dollars per million tokens.
+ * Accumulates the per-model usage breakdown on `global.quota.byModel` so the
+ * agent can report input/output token counts and image spend per model to the
+ * UI. No-ops when the quota global is absent.
  */
-const calculateTextCost = (modelName, usage, config) => {
+const recordModelBreakdown = (modelName, inputCost, outputCost, imageCost, inputTokens = 0, outputTokens = 0) => {
+    const quota = globalThis.quota;
+    if (!quota || !modelName)
+        return;
+    if (!quota.byModel || typeof quota.byModel !== "object")
+        quota.byModel = {};
+    const entry = (quota.byModel[modelName] ||= {
+        inputCost: 0,
+        outputCost: 0,
+        imageCost: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+    });
+    // Entries created by older versions of this module lack the token counters.
+    if (typeof entry.inputTokens !== "number")
+        entry.inputTokens = 0;
+    if (typeof entry.outputTokens !== "number")
+        entry.outputTokens = 0;
+    if (Number.isFinite(inputCost) && inputCost > 0)
+        entry.inputCost += inputCost;
+    if (Number.isFinite(outputCost) && outputCost > 0)
+        entry.outputCost += outputCost;
+    if (Number.isFinite(imageCost) && imageCost > 0)
+        entry.imageCost += imageCost;
+    if (Number.isFinite(inputTokens) && inputTokens > 0)
+        entry.inputTokens += inputTokens;
+    if (Number.isFinite(outputTokens) && outputTokens > 0)
+        entry.outputTokens += outputTokens;
+};
+/**
+ * Computes and records the USD cost of a text LLM call from the
+ * `<model>-input-token-costs` / `<model>-output-token-costs` constants
+ * (dollars per million tokens). Updates both the session total
+ * (`quota.usedThisSession` / `quota.remaining`) and the per-model breakdown
+ * (`quota.byModel`).
+ */
+const recordTextCost = (modelName, usage, config) => {
     if (!usage)
-        return 0;
-    const price = getModelPrice(modelName, config);
-    if (!price)
-        return 0;
-    const inputCost = ((usage.input_tokens || 0) / 1_000_000) * (price.input || 0);
-    const outputCost = ((usage.output_tokens || 0) / 1_000_000) * (price.output || 0);
-    return inputCost + outputCost;
+        return;
+    const inputRate = getModelRate(modelName, config, "input-token") || 0;
+    const outputRate = getModelRate(modelName, config, "output-token") || 0;
+    const inputTokens = usage.input_tokens || 0;
+    const outputTokens = usage.output_tokens || 0;
+    const inputCost = (inputTokens / 1_000_000) * inputRate;
+    const outputCost = (outputTokens / 1_000_000) * outputRate;
+    recordCost(inputCost + outputCost);
+    recordModelBreakdown(modelName, inputCost, outputCost, 0, inputTokens, outputTokens);
 };
 /**
- * Computes USD cost for an image generation call. `config.modelPricing[modelName]`
- * is expected to provide a `perImage` rate in dollars.
+ * Computes and records the USD cost of an image generation call from the
+ * `<model>-image-costs` constant (dollars per generated image). Updates both
+ * the session total and the per-model breakdown.
  */
-const calculateImageCost = (modelName, numImages, config) => {
-    const price = getModelPrice(modelName, config);
-    if (!price)
-        return 0;
-    return (numImages || 0) * (price.perImage || 0);
+const recordImageCost = (modelName, numImages, config) => {
+    const rate = getModelRate(modelName, config, "image") || 0;
+    const imageCost = (numImages || 0) * rate;
+    recordCost(imageCost);
+    recordModelBreakdown(modelName, 0, 0, imageCost);
 };
 /**
  * Extracts a normalized token-usage object from a single LangChain `invoke()`
@@ -569,7 +610,7 @@ const runAgent = async (agent, prompt, config, onProgress = null) => {
             throw err;
         }
     }
-    recordCost(calculateTextCost(modelName, sumAgentResponseUsage(response), config));
+    recordTextCost(modelName, sumAgentResponseUsage(response), config);
     const endTime = Date.now();
     const duration = endTime - startTime;
     logger_js_1.default.log(null, logger_js_1.default.levels.info, `Agent "${agent.options?.name}" completed in ${Math.round(duration / 1000)} seconds.`);
@@ -1044,7 +1085,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                     throw err;
                 }
             }
-            recordCost(calculateTextCost(modelName, streamUsage, config));
+            recordTextCost(modelName, streamUsage, config);
             if (!rawContent) {
                 throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, "LLM returned no content");
             }
@@ -1144,7 +1185,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                     throw err;
                 }
             }
-            recordCost(calculateTextCost(modelName, extractUsageFromInvoke(response), config));
+            recordTextCost(modelName, extractUsageFromInvoke(response), config);
             const rawContent = response?.content || response;
             // If not expecting JSON, return raw content directly
             if (!expectsJsonResponse) {
@@ -1252,7 +1293,7 @@ const generateImageWithOpenAI = async (modelName, config, prompt, options) => {
     }
     assertQuotaAvailable();
     const response = await openai.images.generate(requestParams);
-    recordCost(calculateImageCost(modelName, response.data?.length || n, config));
+    recordImageCost(modelName, response.data?.length || n, config);
     // Format response based on number of images
     if (n === 1) {
         const imageData = response.data[0];
@@ -1369,7 +1410,7 @@ const generateImageWithGoogle = async (modelName, config, prompt, options) => {
     if (images.length === 0) {
         throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, `No images were generated by ${modelName}`);
     }
-    recordCost(calculateImageCost(modelName, images.length, config));
+    recordImageCost(modelName, images.length, config);
     if (numberOfImages === 1 || images.length === 1) {
         return images[0];
     }

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

package/dist/cjs/serve.js

@@ -38,12 +38,9 @@ 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 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 agentProto_js_1 = require("./agentProto.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 {
@@ -66,55 +63,6 @@ const defaultAuthenticate = async (request) => {
         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;
@@ -219,7 +167,7 @@ const serve = (main, options = {}) => {
         void handle();
     };
     const server = new grpc.Server();
-    server.addService(loadAgentService(), { Execute: execute });
+    server.addService((0, agentProto_js_1.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) => {

package/dist/esm/agentProto.d.ts

@@ -0,0 +1,19 @@
+import * as grpc from "@grpc/grpc-js";
+/**
+ * gRPC contract shared by the entire agent fleet — the `serve()` server AND the
+ * relay client. `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`.
+ */
+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";
+/**
+ * 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
+ * cjs/esm dual build. Returns the loaded package (server uses
+ * `.stackfactor.agent.v1.Agent.service`; client uses the `Agent` constructor).
+ */
+export declare const loadAgentPackage: () => any;
+/** The Agent gRPC service definition (for the `serve()` server). */
+export declare const loadAgentService: () => grpc.ServiceDefinition;
+//# sourceMappingURL=agentProto.d.ts.map

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

@@ -0,0 +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"}

package/dist/esm/agentProto.js

@@ -0,0 +1,60 @@
+import * as grpc from "@grpc/grpc-js";
+import * as protoLoader from "@grpc/proto-loader";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+/**
+ * gRPC contract shared by the entire agent fleet — the `serve()` server AND the
+ * relay client. `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`.
+ */
+export 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; }
+`;
+/**
+ * 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
+ * cjs/esm dual build. Returns the loaded package (server uses
+ * `.stackfactor.agent.v1.Agent.service`; client uses the `Agent` constructor).
+ */
+export const loadAgentPackage = () => {
+    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,
+    });
+    return grpc.loadPackageDefinition(packageDefinition);
+};
+/** The Agent gRPC service definition (for the `serve()` server). */
+export const loadAgentService = () => loadAgentPackage().stackfactor.agent.v1.Agent.service;

package/dist/esm/client.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The fleet `Agent.Execute` request. `*_json` fields are JSON strings.
+ * `request_json` MUST include the caller's StackFactor session token as
+ * `authToken` — the agent validates it (via `serve()`'s auth gate) before
+ * running. This is distinct from the Cloud Run ID token (see `CallAgentOptions`).
+ */
+export interface AgentExecuteRequest {
+    content_type: string;
+    data_json: string;
+    config_json: string;
+    request_json: string;
+    event: number;
+}
+export interface CallAgentOptions {
+    /**
+     * Google ID token (audience = the agent's Cloud Run URL) to get past Cloud
+     * Run's `--no-allow-unauthenticated` ingress. Attached as `authorization:
+     * Bearer` metadata. The agent never sees it; ingress consumes it.
+     */
+    idToken?: string;
+    /** Called for each streamed `Progress` frame (e.g. to forward to a socket). */
+    onProgress?: (update: {
+        progress: number;
+        message: string;
+    }) => void;
+    /** Abort the RPC (e.g. the frontend socket dropped) → stops the agent's LLM. */
+    signal?: AbortSignal;
+    /** Call deadline; defaults to 900s to match Cloud Run's max request timeout. */
+    deadlineMs?: number;
+}
+/**
+ * Calls a deployed agent's `Agent.Execute` over gRPC server-streaming. Forwards
+ * each `Progress` frame to `onProgress`, resolves with the parsed `result_json`
+ * on `Result`, and rejects (with `error.code`) on `ErrorInfo`. Caller-cancel via
+ * `options.signal` cancels the RPC.
+ *
+ * @param agentUrl - The agent's Cloud Run URL (https://…run.app).
+ * @param request - The `ExecuteRequest` (its `request_json` carries `authToken`).
+ */
+export declare const callAgent: (agentUrl: string, request: AgentExecuteRequest, options?: CallAgentOptions) => Promise<any>;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +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"}

package/dist/esm/client.js

@@ -0,0 +1,94 @@
+import * as grpc from "@grpc/grpc-js";
+import { loadAgentPackage } from "./agentProto.js";
+const DEFAULT_DEADLINE_MS = 900_000;
+const safeParse = (value, fallback) => {
+    if (!value)
+        return fallback;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+};
+/** Turns an `ErrorInfo` frame into an Error carrying the agent's `code`. */
+const agentError = (frame) => {
+    const error = new Error(frame?.message || "Agent error");
+    error.code = frame?.code;
+    return error;
+};
+/**
+ * Channel credentials for an authenticated Cloud Run agent: TLS (Cloud Run
+ * terminates at the edge) plus per-call metadata carrying the ID token.
+ */
+const buildCredentials = (idToken) => {
+    const ssl = grpc.credentials.createSsl();
+    if (!idToken) {
+        return ssl;
+    }
+    const callCreds = grpc.credentials.createFromMetadataGenerator((_ctx, cb) => {
+        const metadata = new grpc.Metadata();
+        metadata.add("authorization", `Bearer ${idToken}`);
+        cb(null, metadata);
+    });
+    return grpc.credentials.combineChannelCredentials(ssl, callCreds);
+};
+/**
+ * Calls a deployed agent's `Agent.Execute` over gRPC server-streaming. Forwards
+ * each `Progress` frame to `onProgress`, resolves with the parsed `result_json`
+ * on `Result`, and rejects (with `error.code`) on `ErrorInfo`. Caller-cancel via
+ * `options.signal` cancels the RPC.
+ *
+ * @param agentUrl - The agent's Cloud Run URL (https://…run.app).
+ * @param request - The `ExecuteRequest` (its `request_json` carries `authToken`).
+ */
+export const callAgent = (agentUrl, request, 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 stream = client.Execute(request, {
+        deadline: Date.now() + (options.deadlineMs ?? DEFAULT_DEADLINE_MS),
+    });
+    let settled = false;
+    const settle = (run) => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        try {
+            client.close();
+        }
+        catch {
+            // ignore close errors
+        }
+        run();
+    };
+    if (options.signal) {
+        if (options.signal.aborted) {
+            stream.cancel();
+        }
+        else {
+            options.signal.addEventListener("abort", () => stream.cancel(), {
+                once: true,
+            });
+        }
+    }
+    stream.on("data", (update) => {
+        if (update.progress) {
+            options.onProgress?.({
+                progress: update.progress.progress ?? 0,
+                message: update.progress.message ?? "",
+            });
+        }
+        else if (update.result) {
+            const result = safeParse(update.result.result_json, null);
+            settle(() => resolve(result));
+        }
+        else if (update.error) {
+            settle(() => reject(agentError(update.error)));
+        }
+    });
+    stream.on("error", (error) => settle(() => reject(error)));
+    stream.on("end", () => settle(() => reject(new Error("Agent stream ended without a result or error"))));
+});

package/dist/esm/index.d.ts

@@ -3,11 +3,14 @@ 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 * as runtimeContext from "./runtimeContext.js";
 export { constants };
 export { errorHandling };
 export { langChain };
 export { logger };
 export { serve };
+export { callAgent };
+export type { AgentExecuteRequest, CallAgentOptions } 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,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"}
+{"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"}

package/dist/esm/index.js

@@ -3,10 +3,12 @@ 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 * as runtimeContext from "./runtimeContext.js";
 export { constants };
 export { errorHandling };
 export { langChain };
 export { logger };
 export { serve };
+export { callAgent };
 export { runtimeContext };

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":";0CAiD6C,GAAG,KAAG,IAAI;wBAyhB/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;oCAqXF,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;sDAosBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CAn+B8B,GAAG,KAAG,MAAM;mCAoBxC,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAwgCT,wBAQE"}

package/dist/esm/langChain.js

@@ -63,40 +63,81 @@ const recordCost = (cost) => {
     }
 };
 /**
- * Looks up the per-model pricing entry from `config.modelPricing`. Returns `null`
- * when pricing is not configured for the model, in which case cost recording
- * becomes a no-op (the call still succeeds — pricing data is the host's
- * responsibility, not the agent's).
+ * Reads a per-model rate from the flat cost constants the integration defines
+ * in its `config.yaml` (exposed on the config object), e.g.
+ * `claude-opus-4-7-input-token-costs`. Returns `null` when the constant is
+ * absent or not numeric, in which case cost recording becomes a no-op (the
+ * call still succeeds — pricing is the integration's configuration concern).
  */
-const getModelPrice = (modelName, config) => {
-    const pricing = config?.modelPricing;
-    if (!pricing)
+const getModelRate = (modelName, config, kind) => {
+    if (!config || !modelName)
         return null;
-    return pricing[modelName] || null;
+    const rate = Number(config[`${modelName}-${kind}-costs`]);
+    return Number.isFinite(rate) ? rate : null;
 };
 /**
- * Computes USD cost for a text LLM call. `config.modelPricing[modelName]` is
- * expected to provide `input` and `output` rates in dollars per million tokens.
+ * Accumulates the per-model usage breakdown on `global.quota.byModel` so the
+ * agent can report input/output token counts and image spend per model to the
+ * UI. No-ops when the quota global is absent.
  */
-const calculateTextCost = (modelName, usage, config) => {
+const recordModelBreakdown = (modelName, inputCost, outputCost, imageCost, inputTokens = 0, outputTokens = 0) => {
+    const quota = globalThis.quota;
+    if (!quota || !modelName)
+        return;
+    if (!quota.byModel || typeof quota.byModel !== "object")
+        quota.byModel = {};
+    const entry = (quota.byModel[modelName] ||= {
+        inputCost: 0,
+        outputCost: 0,
+        imageCost: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+    });
+    // Entries created by older versions of this module lack the token counters.
+    if (typeof entry.inputTokens !== "number")
+        entry.inputTokens = 0;
+    if (typeof entry.outputTokens !== "number")
+        entry.outputTokens = 0;
+    if (Number.isFinite(inputCost) && inputCost > 0)
+        entry.inputCost += inputCost;
+    if (Number.isFinite(outputCost) && outputCost > 0)
+        entry.outputCost += outputCost;
+    if (Number.isFinite(imageCost) && imageCost > 0)
+        entry.imageCost += imageCost;
+    if (Number.isFinite(inputTokens) && inputTokens > 0)
+        entry.inputTokens += inputTokens;
+    if (Number.isFinite(outputTokens) && outputTokens > 0)
+        entry.outputTokens += outputTokens;
+};
+/**
+ * Computes and records the USD cost of a text LLM call from the
+ * `<model>-input-token-costs` / `<model>-output-token-costs` constants
+ * (dollars per million tokens). Updates both the session total
+ * (`quota.usedThisSession` / `quota.remaining`) and the per-model breakdown
+ * (`quota.byModel`).
+ */
+const recordTextCost = (modelName, usage, config) => {
     if (!usage)
-        return 0;
-    const price = getModelPrice(modelName, config);
-    if (!price)
-        return 0;
-    const inputCost = ((usage.input_tokens || 0) / 1_000_000) * (price.input || 0);
-    const outputCost = ((usage.output_tokens || 0) / 1_000_000) * (price.output || 0);
-    return inputCost + outputCost;
+        return;
+    const inputRate = getModelRate(modelName, config, "input-token") || 0;
+    const outputRate = getModelRate(modelName, config, "output-token") || 0;
+    const inputTokens = usage.input_tokens || 0;
+    const outputTokens = usage.output_tokens || 0;
+    const inputCost = (inputTokens / 1_000_000) * inputRate;
+    const outputCost = (outputTokens / 1_000_000) * outputRate;
+    recordCost(inputCost + outputCost);
+    recordModelBreakdown(modelName, inputCost, outputCost, 0, inputTokens, outputTokens);
 };
 /**
- * Computes USD cost for an image generation call. `config.modelPricing[modelName]`
- * is expected to provide a `perImage` rate in dollars.
+ * Computes and records the USD cost of an image generation call from the
+ * `<model>-image-costs` constant (dollars per generated image). Updates both
+ * the session total and the per-model breakdown.
  */
-const calculateImageCost = (modelName, numImages, config) => {
-    const price = getModelPrice(modelName, config);
-    if (!price)
-        return 0;
-    return (numImages || 0) * (price.perImage || 0);
+const recordImageCost = (modelName, numImages, config) => {
+    const rate = getModelRate(modelName, config, "image") || 0;
+    const imageCost = (numImages || 0) * rate;
+    recordCost(imageCost);
+    recordModelBreakdown(modelName, 0, 0, imageCost);
 };
 /**
  * Extracts a normalized token-usage object from a single LangChain `invoke()`
@@ -564,7 +605,7 @@ const runAgent = async (agent, prompt, config, onProgress = null) => {
             throw err;
         }
     }
-    recordCost(calculateTextCost(modelName, sumAgentResponseUsage(response), config));
+    recordTextCost(modelName, sumAgentResponseUsage(response), config);
     const endTime = Date.now();
     const duration = endTime - startTime;
     logger.log(null, logger.levels.info, `Agent "${agent.options?.name}" completed in ${Math.round(duration / 1000)} seconds.`);
@@ -1039,7 +1080,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                     throw err;
                 }
             }
-            recordCost(calculateTextCost(modelName, streamUsage, config));
+            recordTextCost(modelName, streamUsage, config);
             if (!rawContent) {
                 throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, "LLM returned no content");
             }
@@ -1139,7 +1180,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                     throw err;
                 }
             }
-            recordCost(calculateTextCost(modelName, extractUsageFromInvoke(response), config));
+            recordTextCost(modelName, extractUsageFromInvoke(response), config);
             const rawContent = response?.content || response;
             // If not expecting JSON, return raw content directly
             if (!expectsJsonResponse) {
@@ -1247,7 +1288,7 @@ const generateImageWithOpenAI = async (modelName, config, prompt, options) => {
     }
     assertQuotaAvailable();
     const response = await openai.images.generate(requestParams);
-    recordCost(calculateImageCost(modelName, response.data?.length || n, config));
+    recordImageCost(modelName, response.data?.length || n, config);
     // Format response based on number of images
     if (n === 1) {
         const imageData = response.data[0];
@@ -1364,7 +1405,7 @@ const generateImageWithGoogle = async (modelName, config, prompt, options) => {
     if (images.length === 0) {
         throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, `No images were generated by ${modelName}`);
     }
-    recordCost(calculateImageCost(modelName, images.length, config));
+    recordImageCost(modelName, images.length, config);
     if (numberOfImages === 1 || images.length === 1) {
         return images[0];
     }

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

package/dist/esm/serve.js

@@ -1,10 +1,7 @@
 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 { loadAgentService } from "./agentProto.js";
 import { runWithContext, installGlobals } from "./runtimeContext.js";
 /** Marks an auth failure so the handler can map it to gRPC UNAUTHENTICATED. */
 class UnauthenticatedError extends Error {
@@ -27,55 +24,6 @@ const defaultAuthenticate = async (request) => {
         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;

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@stackfactor/agent-utils",
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",