agentic-server 0.25.1 → 0.26.0

package/esm/router.js

@@ -46,6 +46,25 @@ function upstreamErrorMessage(provider, status, body) {
         ? `${provider.type} provider error ${status}: ${reason}`
         : `${provider.type} provider error ${status}`;
 }
+/**
+ * Who the call is for and which task it is a cost of. Identity comes from the
+ * caller's identity headers; task linkage from the correlation headers the
+ * runtimes forward (`X-Invocation-Id`, `X-Job-Id`, `X-Attempt`, `X-Run-Id`).
+ * `X-Attempt` must be a non-negative integer or it is dropped.
+ */
+export const readAttribution = (req) => {
+    const rawAttempt = req.get('X-Attempt');
+    const attempt = typeof rawAttempt === 'string' && /^\d+$/.test(rawAttempt) ? Number(rawAttempt) : undefined;
+    return {
+        databaseId: req.get('X-Database-Id'),
+        entityId: req.get('X-Entity-Id'),
+        actorId: req.get('X-Actor-Id'),
+        invocationId: req.get('X-Invocation-Id'),
+        jobId: req.get('X-Job-Id'),
+        attempt,
+        runId: req.get('X-Run-Id')
+    };
+};
 export const createRouter = (options) => {
     const router = Router();
     // Metering is backend-agnostic: the caller injects an InferenceSink. When
@@ -58,8 +77,8 @@ export const createRouter = (options) => {
             res.status(400).json({ error: { message: 'X-Database-Id is required' } });
             return;
         }
-        const entityId = req.get('X-Entity-Id');
-        const actorId = req.get('X-Actor-Id');
+        const attribution = readAttribution(req);
+        const { entityId } = attribution;
         const requestProvider = req.get('X-LLM-Provider');
         const startTime = process.hrtime.bigint();
         const provider = resolveProvider(options, req.body?.model, requestProvider);
@@ -109,7 +128,7 @@ export const createRouter = (options) => {
                 log.error('upstream error', { status: upstream.status, provider: provider.type, body: text });
                 if (sink) {
                     sink.logInference({
-                        databaseId, entityId, actorId,
+                        ...attribution,
                         model: String(req.body?.model || body.model || ''),
                         provider: provider.type,
                         service: 'chat',
@@ -138,7 +157,7 @@ export const createRouter = (options) => {
                 });
                 if (sink) {
                     sink.logInference({
-                        databaseId, entityId, actorId,
+                        ...attribution,
                         model: String(req.body?.model || body.model || ''),
                         provider: provider.type,
                         service: 'chat',
@@ -164,7 +183,7 @@ export const createRouter = (options) => {
             });
             if (sink) {
                 sink.logInference({
-                    databaseId, entityId, actorId,
+                    ...attribution,
                     model: String(req.body?.model || body.model || ''),
                     provider: provider.type,
                     service: 'chat',
@@ -184,7 +203,7 @@ export const createRouter = (options) => {
             log.error('chat/completions error', err);
             if (sink) {
                 sink.logInference({
-                    databaseId, entityId, actorId,
+                    ...attribution,
                     model: String(req.body?.model || ''),
                     provider: provider.type,
                     service: 'chat',
@@ -213,8 +232,8 @@ export const createRouter = (options) => {
             res.status(400).json({ error: { message: 'X-Database-Id is required' } });
             return;
         }
-        const entityId = req.get('X-Entity-Id');
-        const actorId = req.get('X-Actor-Id');
+        const attribution = readAttribution(req);
+        const { entityId } = attribution;
         const requestProvider = req.get('X-LLM-Provider');
         const startTime = process.hrtime.bigint();
         const provider = resolveProvider(options, req.body?.model, requestProvider);
@@ -234,7 +253,7 @@ export const createRouter = (options) => {
                 log.error('upstream embed error', { status: upstream.status, provider: provider.type });
                 if (sink) {
                     sink.logInference({
-                        databaseId, entityId, actorId,
+                        ...attribution,
                         model: String(req.body?.model || body.model || ''),
                         provider: provider.type,
                         service: 'embed',
@@ -255,7 +274,7 @@ export const createRouter = (options) => {
             log.info('embed complete', { databaseId, entityId, provider: provider.type });
             if (sink) {
                 sink.logInference({
-                    databaseId, entityId, actorId,
+                    ...attribution,
                     model: String(req.body?.model || body.model || ''),
                     provider: provider.type,
                     service: 'embed',
@@ -275,7 +294,7 @@ export const createRouter = (options) => {
             log.error('embeddings error', err);
             if (sink) {
                 sink.logInference({
-                    databaseId, entityId, actorId,
+                    ...attribution,
                     model: String(req.body?.model || ''),
                     provider: provider.type,
                     service: 'embed',
@@ -298,8 +317,7 @@ export const createRouter = (options) => {
             res.status(400).json({ error: { message: 'X-Database-Id is required' } });
             return;
         }
-        const entityId = req.get('X-Entity-Id');
-        const actorId = req.get('X-Actor-Id');
+        const attribution = readAttribution(req);
         const { model, provider: reportedProvider, service, operation, input_tokens, output_tokens, total_tokens, latency_ms, status, error_type, raw_usage } = req.body || {};
         if (!model) {
             res.status(400).json({ error: { message: 'model is required' } });
@@ -307,9 +325,7 @@ export const createRouter = (options) => {
         }
         if (sink) {
             sink.logInference({
-                databaseId,
-                entityId,
-                actorId,
+                ...attribution,
                 model: String(model),
                 provider: String(reportedProvider || 'unknown'),
                 service: (service === 'embed' ? 'embed' : 'chat'),

package/esm/server.js

@@ -1,10 +1,17 @@
 import express from 'express';
 import { createRouter } from './router';
-/** Identity headers trusted only when isPublic === false (private network). */
+/** Identity + task-correlation headers trusted only when isPublic === false
+ *  (private network). The correlation headers say which invocation/job/attempt/
+ *  run a model call is a cost of; an external client must not be able to pin
+ *  its usage onto someone else's task. */
 const IDENTITY_HEADERS = [
     'x-database-id',
     'x-entity-id',
-    'x-actor-id'
+    'x-actor-id',
+    'x-invocation-id',
+    'x-job-id',
+    'x-attempt',
+    'x-run-id'
 ];
 /**
  * Create a standalone Express app for the agentic server.

package/index.d.ts

@@ -25,4 +25,4 @@ export { buildProviderHeaders, resolveProvider, resolveUpstreamUrl } from './pro
 export { createRouter } from './router';
 export type { AgenticServerStartOptions } from './server';
 export { createAgenticServer } from './server';
-export type { AgenticServerOptions, InferenceEntry, InferenceSink, ProviderConfig, ResolvedProvider, UsageResult } from './types';
+export type { AgenticServerOptions, InferenceAttribution, InferenceEntry, InferenceSink, ProviderConfig, ResolvedProvider, UsageResult } from './types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-server",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "description": "Standalone OpenAI-compatible LLM gateway — multi-provider proxy with pluggable inference metering",
   "main": "index.js",
   "module": "esm/index.js",
@@ -29,13 +29,13 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@pgpmjs/logger": "^2.25.0"
+    "@pgpmjs/logger": "^2.25.1"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",
     "@types/node": "^22.19.11",
     "express": "^5.2.1",
-    "makage": "^0.3.0"
+    "makage": "^0.8.0"
   },
   "peerDependencies": {
     "express": "^5.0.0"
@@ -51,5 +51,5 @@
     "metering",
     "constructive"
   ],
-  "gitHead": "f9611d3a1ba8bdb50a39b5bca7c9a7115df96e34"
+  "gitHead": "cc30249ddf84bc8c410d9681adb15f98228ab591"
 }

package/router.d.ts

@@ -10,5 +10,12 @@
  *   - /v1/usage reporting endpoint for external usage submission
  */
 import { Router } from 'express';
-import type { AgenticServerOptions } from './types';
+import type { AgenticServerOptions, InferenceAttribution } from './types';
+/**
+ * Who the call is for and which task it is a cost of. Identity comes from the
+ * caller's identity headers; task linkage from the correlation headers the
+ * runtimes forward (`X-Invocation-Id`, `X-Job-Id`, `X-Attempt`, `X-Run-Id`).
+ * `X-Attempt` must be a non-negative integer or it is dropped.
+ */
+export declare const readAttribution: (req: any) => InferenceAttribution;
 export declare const createRouter: (options: AgenticServerOptions) => Router;

package/router.js

@@ -11,7 +11,7 @@
  *   - /v1/usage reporting endpoint for external usage submission
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createRouter = void 0;
+exports.createRouter = exports.readAttribution = void 0;
 const logger_1 = require("@pgpmjs/logger");
 const express_1 = require("express");
 const providers_1 = require("./providers");
@@ -49,6 +49,26 @@ function upstreamErrorMessage(provider, status, body) {
         ? `${provider.type} provider error ${status}: ${reason}`
         : `${provider.type} provider error ${status}`;
 }
+/**
+ * Who the call is for and which task it is a cost of. Identity comes from the
+ * caller's identity headers; task linkage from the correlation headers the
+ * runtimes forward (`X-Invocation-Id`, `X-Job-Id`, `X-Attempt`, `X-Run-Id`).
+ * `X-Attempt` must be a non-negative integer or it is dropped.
+ */
+const readAttribution = (req) => {
+    const rawAttempt = req.get('X-Attempt');
+    const attempt = typeof rawAttempt === 'string' && /^\d+$/.test(rawAttempt) ? Number(rawAttempt) : undefined;
+    return {
+        databaseId: req.get('X-Database-Id'),
+        entityId: req.get('X-Entity-Id'),
+        actorId: req.get('X-Actor-Id'),
+        invocationId: req.get('X-Invocation-Id'),
+        jobId: req.get('X-Job-Id'),
+        attempt,
+        runId: req.get('X-Run-Id')
+    };
+};
+exports.readAttribution = readAttribution;
 const createRouter = (options) => {
     const router = (0, express_1.Router)();
     // Metering is backend-agnostic: the caller injects an InferenceSink. When
@@ -61,8 +81,8 @@ const createRouter = (options) => {
             res.status(400).json({ error: { message: 'X-Database-Id is required' } });
             return;
         }
-        const entityId = req.get('X-Entity-Id');
-        const actorId = req.get('X-Actor-Id');
+        const attribution = (0, exports.readAttribution)(req);
+        const { entityId } = attribution;
         const requestProvider = req.get('X-LLM-Provider');
         const startTime = process.hrtime.bigint();
         const provider = (0, providers_1.resolveProvider)(options, req.body?.model, requestProvider);
@@ -112,7 +132,7 @@ const createRouter = (options) => {
                 log.error('upstream error', { status: upstream.status, provider: provider.type, body: text });
                 if (sink) {
                     sink.logInference({
-                        databaseId, entityId, actorId,
+                        ...attribution,
                         model: String(req.body?.model || body.model || ''),
                         provider: provider.type,
                         service: 'chat',
@@ -141,7 +161,7 @@ const createRouter = (options) => {
                 });
                 if (sink) {
                     sink.logInference({
-                        databaseId, entityId, actorId,
+                        ...attribution,
                         model: String(req.body?.model || body.model || ''),
                         provider: provider.type,
                         service: 'chat',
@@ -167,7 +187,7 @@ const createRouter = (options) => {
             });
             if (sink) {
                 sink.logInference({
-                    databaseId, entityId, actorId,
+                    ...attribution,
                     model: String(req.body?.model || body.model || ''),
                     provider: provider.type,
                     service: 'chat',
@@ -187,7 +207,7 @@ const createRouter = (options) => {
             log.error('chat/completions error', err);
             if (sink) {
                 sink.logInference({
-                    databaseId, entityId, actorId,
+                    ...attribution,
                     model: String(req.body?.model || ''),
                     provider: provider.type,
                     service: 'chat',
@@ -216,8 +236,8 @@ const createRouter = (options) => {
             res.status(400).json({ error: { message: 'X-Database-Id is required' } });
             return;
         }
-        const entityId = req.get('X-Entity-Id');
-        const actorId = req.get('X-Actor-Id');
+        const attribution = (0, exports.readAttribution)(req);
+        const { entityId } = attribution;
         const requestProvider = req.get('X-LLM-Provider');
         const startTime = process.hrtime.bigint();
         const provider = (0, providers_1.resolveProvider)(options, req.body?.model, requestProvider);
@@ -237,7 +257,7 @@ const createRouter = (options) => {
                 log.error('upstream embed error', { status: upstream.status, provider: provider.type });
                 if (sink) {
                     sink.logInference({
-                        databaseId, entityId, actorId,
+                        ...attribution,
                         model: String(req.body?.model || body.model || ''),
                         provider: provider.type,
                         service: 'embed',
@@ -258,7 +278,7 @@ const createRouter = (options) => {
             log.info('embed complete', { databaseId, entityId, provider: provider.type });
             if (sink) {
                 sink.logInference({
-                    databaseId, entityId, actorId,
+                    ...attribution,
                     model: String(req.body?.model || body.model || ''),
                     provider: provider.type,
                     service: 'embed',
@@ -278,7 +298,7 @@ const createRouter = (options) => {
             log.error('embeddings error', err);
             if (sink) {
                 sink.logInference({
-                    databaseId, entityId, actorId,
+                    ...attribution,
                     model: String(req.body?.model || ''),
                     provider: provider.type,
                     service: 'embed',
@@ -301,8 +321,7 @@ const createRouter = (options) => {
             res.status(400).json({ error: { message: 'X-Database-Id is required' } });
             return;
         }
-        const entityId = req.get('X-Entity-Id');
-        const actorId = req.get('X-Actor-Id');
+        const attribution = (0, exports.readAttribution)(req);
         const { model, provider: reportedProvider, service, operation, input_tokens, output_tokens, total_tokens, latency_ms, status, error_type, raw_usage } = req.body || {};
         if (!model) {
             res.status(400).json({ error: { message: 'model is required' } });
@@ -310,9 +329,7 @@ const createRouter = (options) => {
         }
         if (sink) {
             sink.logInference({
-                databaseId,
-                entityId,
-                actorId,
+                ...attribution,
                 model: String(model),
                 provider: String(reportedProvider || 'unknown'),
                 service: (service === 'embed' ? 'embed' : 'chat'),

package/server.js

@@ -6,11 +6,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAgenticServer = void 0;
 const express_1 = __importDefault(require("express"));
 const router_1 = require("./router");
-/** Identity headers trusted only when isPublic === false (private network). */
+/** Identity + task-correlation headers trusted only when isPublic === false
+ *  (private network). The correlation headers say which invocation/job/attempt/
+ *  run a model call is a cost of; an external client must not be able to pin
+ *  its usage onto someone else's task. */
 const IDENTITY_HEADERS = [
     'x-database-id',
     'x-entity-id',
-    'x-actor-id'
+    'x-actor-id',
+    'x-invocation-id',
+    'x-job-id',
+    'x-attempt',
+    'x-run-id'
 ];
 /**
  * Create a standalone Express app for the agentic server.

package/types.d.ts

@@ -23,6 +23,8 @@ export interface AgenticServerOptions {
      *  When false (default), the server is deployed behind a private network
      *  (Docker network, K8s service mesh) and trusts identity headers directly:
      *    X-Database-Id, X-Entity-Id, X-Actor-Id
+     *  and the task-correlation headers
+     *    X-Invocation-Id, X-Job-Id, X-Attempt, X-Run-Id
      *  When true, identity headers are stripped from incoming requests
      *  (external clients cannot set tenant context). */
     isPublic?: boolean;
@@ -46,10 +48,20 @@ export interface UsageResult {
 export interface InferenceSink {
     logInference(entry: InferenceEntry): void;
 }
+/** The identity + task-linkage slice of an InferenceEntry, read from headers. */
+export type InferenceAttribution = Pick<InferenceEntry, 'databaseId' | 'entityId' | 'actorId' | 'invocationId' | 'jobId' | 'attempt' | 'runId'>;
 export interface InferenceEntry {
     databaseId: string;
     entityId?: string;
     actorId?: string;
+    /** Task linkage — the invocation / job / attempt / agent run this call is a
+     *  cost of. Inference is COGS attributed to the task the customer was
+     *  charged for; it is never a customer meter of its own. Absent when the
+     *  call was served outside an invocation. */
+    invocationId?: string;
+    jobId?: string;
+    attempt?: number;
+    runId?: string;
     model: string;
     provider: string;
     service: 'chat' | 'embed';