@stigg/agent-sdk-js 0.7.1 → 0.7.3

package/README.md

@@ -148,6 +148,8 @@ closed, and conflating them is how an outage takes an application down.
 | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/gemini.svg" width="18" alt=""> | Gemini | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/typesafe.png" width="18" alt=""> | TypeSafe |
 | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/groq.svg" width="18" alt=""> | Groq | | |
 
+**Frameworks** — [Vercel AI SDK](docs/vercel-ai.md): any model it runs, through `generateText`, `streamText` and agents. Model calls only, for now.
+
 **Gateways** — what was actually *charged*, and which model actually served after routing:
 
 | | Gateway | | Gateway |
@@ -181,6 +183,7 @@ rather than handing back a client that quietly meters nothing.
 | Meter a gateway you operate | `client.stigg.headers()` out, `stigg.ingestFromHeaders(...)` back |
 | Govern a LangChain / LangGraph agent graph ([guide](docs/langchain.md)) | `new StiggLangChainCallbackHandler({ stigg, agents, tools })` from `@stigg/agent-sdk-js/langchain` |
 | Govern a Google ADK agent graph ([guide](docs/guide.md#google-adk-one-plugin-per-runner)) | `new StiggAdkPlugin({ stigg, agents, tools, stepContext })` from `@stigg/agent-sdk-js/adk`, in the Runner's `plugins` |
+| Govern a Vercel AI SDK model or agent ([guide](docs/vercel-ai.md)) | `wrapLanguageModel({ model, middleware: stiggVercelMiddleware({ stigg, stiggContext }) })`, a call's own in `providerOptions.stigg` |
 | Govern a graph from your own harness | `stigg.middleware({ stiggContext, agents })` |
 
 One wrapped client serves every customer and every agent: the context is an argument, given once at

package/dist/bindings/orchestrator/core/agent-middleware.js

@@ -270,6 +270,9 @@ function createAgentMiddleware(session, config) {
                 return;
             }
             await session.ingestMeasurement(step.context, measurement);
+            // Reported what it could, and said what it could not - as a gated client call does.
+            if (measurement.incomplete)
+                session.failedToMeasure(step.context, new Error(measurement.incomplete));
         },
         async startTool(runId, { name, callId, kind, input }, attribution) {
             // Never taken, only looked up - the cap drops old ones: a tools node that runs again, before

package/dist/bindings/orchestrator/vercel-ai/middleware.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The Vercel AI SDK binding: a language model middleware, for `wrapLanguageModel`.
+ *
+ *   const model = wrapLanguageModel({ model: anthropic(MODEL), middleware: stiggVercelMiddleware({ stigg, stiggContext }) });
+ *   await generateText({ model, prompt, providerOptions: { stigg: { customerId } } });
+ *
+ * Every step of `generateText`, `streamText` and an agent's loop is one model call, so each one is
+ * checked before it runs and reported after, through the same core as the LangChain and ADK
+ * bindings. A call's own `stiggContext` rides `providerOptions.stigg`, and is taken out before the
+ * provider sees the call. Nothing here imports `ai`: a middleware is a plain object. See
+ * docs/vercel-ai.md.
+ */
+import type { StiggAgentSDK } from '../../../stigg-agent-sdk';
+import type { SessionHooks } from '../../../core/session';
+import type { ClientContext, GovernedAgentMiddleware, Measurement } from '../../../types';
+export { VERCEL_AI_METRICS, measurementOf } from './usage';
+export type { VercelAIMetric, VercelAIMetrics } from './usage';
+export type StiggVercelMiddlewareOptions = {
+    stigg: StiggAgentSDK;
+    /** Every call's context - typically the agent's `agentId` and what it gates on. A call's `providerOptions.stigg` is laid over it. */
+    stiggContext?: ClientContext;
+    hooks?: SessionHooks;
+};
+/**
+ * What `wrapLanguageModel` takes, typed here so this package does not import `ai`. `v3` is what
+ * `ai` 6 requires; `ai` 7 accepts any version and runs it the same way.
+ */
+export type StiggVercelMiddleware = {
+    readonly specificationVersion: 'v3';
+    transformParams(options: {
+        params: any;
+    }): Promise<any>;
+    wrapGenerate(options: {
+        doGenerate: () => PromiseLike<any>;
+        params: any;
+    }): Promise<any>;
+    wrapStream(options: {
+        doStream: () => PromiseLike<any>;
+        params: any;
+    }): Promise<any>;
+    /** What this middleware did, and what is still in flight. */
+    readonly stigg: GovernedAgentMiddleware['stigg'];
+};
+export declare function stiggVercelMiddleware({ stigg, stiggContext, hooks, }: StiggVercelMiddlewareOptions): StiggVercelMiddleware;
+/**
+ * Calls `done` once, when the stream ends: read to the end, failed, cancelled, or stopped by the
+ * call's `abortSignal` - which is how the AI SDK stops a stream, without cancelling it.
+ * ponytail: a reader that stops with no `abortSignal` is not reported; nothing tells this layer.
+ */
+export declare function observeStream(result: any, signal: AbortSignal | undefined, done: (measurement: Measurement | undefined) => void): void;

package/dist/bindings/orchestrator/vercel-ai/middleware.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.measurementOf = exports.VERCEL_AI_METRICS = void 0;
+exports.stiggVercelMiddleware = stiggVercelMiddleware;
+exports.observeStream = observeStream;
+const usage_1 = require("./usage");
+var usage_2 = require("./usage");
+Object.defineProperty(exports, "VERCEL_AI_METRICS", { enumerable: true, get: function () { return usage_2.VERCEL_AI_METRICS; } });
+Object.defineProperty(exports, "measurementOf", { enumerable: true, get: function () { return usage_2.measurementOf; } });
+const MISSING_CUSTOMER = 'Name it on every call as `providerOptions: { stigg: { customerId } }`, ' +
+    'or give the middleware a default in its `stiggContext: { customerId }`.';
+function stiggVercelMiddleware({ stigg, stiggContext, hooks, }) {
+    if (!stigg || typeof stigg.middleware !== 'function') {
+        throw new Error('stiggVercelMiddleware needs `stigg`: the StiggAgentSDK instance to govern through.');
+    }
+    const governance = stigg.middleware({ stiggContext, hooks, missingCustomer: MISSING_CUSTOMER });
+    // `doGenerate()` takes no arguments: the model is called with what `transformParams` returned.
+    // So the context comes out there, and is found again by that params object.
+    const contexts = new WeakMap();
+    // A step's id only has to be unique among this middleware's own steps in flight.
+    let steps = 0;
+    // A stream reports when it ends, after `wrapStream` has returned - so the call's next step waits
+    // for those reports here, and is checked against their spend. Keyed by the call: the AI SDK hands
+    // every step of one call the same `providerOptions.stigg` object, so other calls - other users
+    // of the same customer included - never queue behind it. A call with no context of its own falls
+    // back to its customer and agent. `endModel` never rejects.
+    const reporting = new Map();
+    const callOf = (params) => contexts.get(params) ?? JSON.stringify([stiggContext?.customerId, stiggContext?.agentId]);
+    /** Checks the step, as the agent and customer this call names. Refused: `AccessDeniedError`. */
+    const start = async (params, event) => {
+        // Once: a call's steps run one after another, so nothing of its own lands while this waits.
+        await Promise.all(reporting.get(callOf(params)) ?? []);
+        const runId = String(++steps);
+        const context = contexts.get(params);
+        await governance.startModel(runId, { stiggContexts: context ? [context] : [] }, event);
+        return runId;
+    };
+    return {
+        specificationVersion: 'v3',
+        stigg: governance.stigg,
+        async transformParams({ params }) {
+            const options = params?.providerOptions;
+            if (!options || typeof options !== 'object' || !('stigg' in options))
+                return params;
+            // The AI Gateway posts call options whole, and the customer and agent ids are not Vercel's to receive.
+            const { stigg: context, ...rest } = options;
+            if (context !== null && (typeof context !== 'object' || Array.isArray(context))) {
+                throw new TypeError(`\`providerOptions.stigg\` must be a stiggContext object, or null for none - got ${typeof context}.`);
+            }
+            const stripped = { ...params, providerOptions: rest };
+            if (context)
+                contexts.set(stripped, context);
+            return stripped;
+        },
+        async wrapGenerate({ doGenerate, params }) {
+            const runId = await start(params, 'vercel-ai.generate');
+            let result;
+            try {
+                result = await doGenerate();
+            }
+            catch (err) {
+                governance.abandon(runId);
+                throw err;
+            }
+            // Awaited, so the agent's next step is checked against this one's spend. Never throws; no
+            // usage at all is reported as a metering failure.
+            await governance.endModel(runId, (0, usage_1.measurementOf)(result?.usage, result?.response?.id));
+            return result;
+        },
+        async wrapStream({ doStream, params }) {
+            const runId = await start(params, 'vercel-ai.stream');
+            let result;
+            try {
+                result = await doStream();
+            }
+            catch (err) {
+                governance.abandon(runId);
+                throw err;
+            }
+            observeStream(result, params?.abortSignal, (measurement) => {
+                if (!measurement)
+                    return governance.abandon(runId);
+                const call = callOf(params);
+                const pending = reporting.get(call) ?? new Set();
+                reporting.set(call, pending);
+                const report = governance.endModel(runId, measurement);
+                pending.add(report);
+                void report.finally(() => {
+                    pending.delete(report);
+                    if (pending.size === 0 && reporting.get(call) === pending)
+                        reporting.delete(call);
+                });
+            });
+            return result;
+        },
+    };
+}
+/** What a stream has told us so far. */
+function streamTally() {
+    let usage;
+    let responseId;
+    let chars = 0;
+    return {
+        /** Never throws: a malformed part is simply not counted. */
+        record(part) {
+            if (part?.type === 'finish')
+                usage = part.usage;
+            else if (part?.type === 'response-metadata' && typeof part.id === 'string')
+                responseId = part.id;
+            else if (typeof part?.delta === 'string')
+                chars += part.delta.length;
+        },
+        /** The usage the model stated; else an estimate; else nothing, for an attempt that produced nothing. */
+        measurement() {
+            const measured = (0, usage_1.measurementOf)(usage, responseId);
+            if (measured)
+                return measured;
+            if (chars === 0 && responseId === undefined)
+                return undefined;
+            return (0, usage_1.estimated)(chars);
+        },
+    };
+}
+/**
+ * Calls `done` once, when the stream ends: read to the end, failed, cancelled, or stopped by the
+ * call's `abortSignal` - which is how the AI SDK stops a stream, without cancelling it.
+ * ponytail: a reader that stops with no `abortSignal` is not reported; nothing tells this layer.
+ */
+function observeStream(result, signal, done) {
+    const source = result?.stream;
+    if (typeof source?.getReader !== 'function') {
+        done(undefined);
+        return;
+    }
+    const tally = streamTally();
+    let reported = false;
+    const report = () => {
+        if (reported)
+            return;
+        reported = true;
+        // Every step of a loop shares the signal, which may live as long as the process.
+        signal?.removeEventListener('abort', report);
+        done(tally.measurement());
+    };
+    signal?.addEventListener('abort', report, { once: true });
+    if (signal?.aborted)
+        report();
+    // A source of its own rather than a TransformStream, whose flush never runs on a cancel.
+    const reader = source.getReader();
+    result.stream = new ReadableStream({
+        async pull(controller) {
+            const next = await reader.read().catch((err) => {
+                report();
+                throw err;
+            });
+            if (next.done) {
+                report();
+                controller.close();
+                return;
+            }
+            tally.record(next.value);
+            controller.enqueue(next.value);
+        },
+        async cancel(reason) {
+            report();
+            await reader.cancel(reason);
+        },
+    });
+}

package/dist/bindings/orchestrator/vercel-ai/usage.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A Vercel AI SDK model's usage, as this SDK reports it.
+ *
+ * The counters overlap the way OpenAI's do - `input_tokens` already counts the cache - so a meter can
+ * price cached input at its own rate. The normalized `usage` a mapper reads is disjoint.
+ */
+import type { Measurement } from '../../../types';
+export declare const VERCEL_AI_METRICS: readonly ["input_tokens", "output_tokens", "cache_read_tokens", "cache_write_tokens", "total_tokens"];
+/** One of the metric names a Vercel AI SDK model reports. */
+export type VercelAIMetric = (typeof VERCEL_AI_METRICS)[number];
+/** What a mapper reads off a Vercel AI SDK call: those names, each possibly absent. */
+export type VercelAIMetrics = Partial<Record<VercelAIMetric, number>>;
+/** `LanguageModelV3Usage` and `V4` alike: `inputTokens.total` includes the cache. */
+export type ModelUsage = {
+    inputTokens?: {
+        total?: number;
+        noCache?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+    };
+    outputTokens?: {
+        total?: number;
+    };
+    raw?: unknown;
+};
+/** One call's usage, or undefined when the model stated no counter - not a call that cost nothing. */
+export declare function measurementOf(usage: ModelUsage | undefined, responseId?: string): Measurement | undefined;
+/** A stream stopped before stating usage: its output, estimated from the text. Its input is unknown. */
+export declare function estimated(chars: number): Measurement;

package/dist/bindings/orchestrator/vercel-ai/usage.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERCEL_AI_METRICS = void 0;
+exports.measurementOf = measurementOf;
+exports.estimated = estimated;
+exports.VERCEL_AI_METRICS = [
+    'input_tokens',
+    'output_tokens',
+    'cache_read_tokens',
+    'cache_write_tokens',
+    'total_tokens',
+];
+/** Roughly, for a stopped stream only - the Anthropic recipe's estimate too. */
+const CHARS_PER_OUTPUT_TOKEN = 4;
+/** One call's usage, or undefined when the model stated no counter - not a call that cost nothing. */
+function measurementOf(usage, responseId) {
+    const input = usage?.inputTokens?.total;
+    const output = usage?.outputTokens?.total;
+    if (input === undefined && output === undefined)
+        return undefined;
+    const cacheRead = usage?.inputTokens?.cacheRead;
+    const cacheWrite = usage?.inputTokens?.cacheWrite;
+    const metrics = numbersOnly({
+        input_tokens: input,
+        output_tokens: output,
+        cache_read_tokens: cacheRead,
+        cache_write_tokens: cacheWrite,
+        total_tokens: (input ?? 0) + (output ?? 0),
+    });
+    const tokenUsage = {
+        input: usage?.inputTokens?.noCache ?? Math.max(0, (input ?? 0) - (cacheRead ?? 0) - (cacheWrite ?? 0)),
+        output: output ?? 0,
+        cacheRead: cacheRead ?? 0,
+        cacheCreate: cacheWrite ?? 0,
+    };
+    const raw = usage?.raw;
+    return {
+        metrics,
+        usage: tokenUsage,
+        ...(raw && typeof raw === 'object' && !Array.isArray(raw) ? { raw: raw } : {}),
+        ...(input === undefined || output === undefined ? { incomplete: 'the model stated only part of its usage' } : {}),
+        // The provider's own id, so a retried step that replays a reply is one report.
+        ...(responseId ? { idempotencyKey: responseId } : {}),
+    };
+}
+/** A stream stopped before stating usage: its output, estimated from the text. Its input is unknown. */
+function estimated(chars) {
+    const output = chars > 0 ? Math.max(1, Math.ceil(chars / CHARS_PER_OUTPUT_TOKEN)) : 0;
+    return {
+        metrics: output ? { output_tokens: output, total_tokens: output } : {},
+        usage: { input: 0, output, cacheRead: 0, cacheCreate: 0 },
+        ...(output ? { estimated: true } : {}),
+        incomplete: 'the stream ended before the model stated its usage',
+    };
+}
+function numbersOnly(stated) {
+    const metrics = {};
+    for (const [name, value] of Object.entries(stated)) {
+        if (typeof value === 'number' && Number.isFinite(value))
+            metrics[name] = value;
+    }
+    return metrics;
+}

package/dist/index.d.ts

@@ -62,4 +62,6 @@ export { weightedMetrics } from './bindings/shared/weighted-metrics';
 export type { WeightedMetricsOptions } from './bindings/shared/weighted-metrics';
 export type { ProxyIngestInput } from './bindings/proxy';
 export type { AgentMiddleware, IssuedToolCall, StepAttribution, ToolStep, } from './bindings/orchestrator/core/agent-middleware';
+export { stiggVercelMiddleware } from './bindings/orchestrator/vercel-ai/middleware';
+export type { StiggVercelMiddleware, StiggVercelMiddlewareOptions, VercelAIMetric, VercelAIMetrics, } from './bindings/orchestrator/vercel-ai/middleware';
 export { normalizedMetrics, normalizeUsage } from './bindings/shared/token-usage';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeUsage = exports.normalizedMetrics = exports.weightedMetrics = exports.estimateFromState = exports.typesafeRecipe = exports.cloudflareRecipe = exports.bedrockRecipe = exports.databricksExternalRecipe = exports.databricksRecipe = exports.ollamaRecipe = exports.mistralRecipe = exports.groqRecipe = exports.litellmRecipe = exports.openrouterRecipe = exports.estimateFromMaxOutputTokens = exports.geminiChatRecipe = exports.geminiRecipe = exports.openAIRecipe = exports.estimateFromMaxTokens = exports.anthropicRecipe = exports.hasMethod = exports.createClientRegistry = exports.wrapClient = exports.toMeasurement = exports.entitlementRef = exports.entitlementKind = exports.entitlementId = exports.emptyTokenUsage = exports.vendorMetrics = exports.unitsPerTokens = exports.looksLikeGovernanceNotEnabled = exports.isGovernanceNotEnabled = exports.isAccessDenied = exports.isEngineError = exports.GovernanceNotEnabledError = exports.AccessDeniedError = exports.EngineError = exports.STIGG_TRACER_NAME = exports.noopLogger = exports.consoleLogger = exports.parseGovernanceHeaders = exports.GOVERNANCE_HEADERS = exports.remedyMessage = exports.describeDecision = exports.flattenRaw = exports.RAW_PREFIX = exports.StiggAgentSDK = void 0;
+exports.normalizeUsage = exports.normalizedMetrics = exports.stiggVercelMiddleware = exports.weightedMetrics = exports.estimateFromState = exports.typesafeRecipe = exports.cloudflareRecipe = exports.bedrockRecipe = exports.databricksExternalRecipe = exports.databricksRecipe = exports.ollamaRecipe = exports.mistralRecipe = exports.groqRecipe = exports.litellmRecipe = exports.openrouterRecipe = exports.estimateFromMaxOutputTokens = exports.geminiChatRecipe = exports.geminiRecipe = exports.openAIRecipe = exports.estimateFromMaxTokens = exports.anthropicRecipe = exports.hasMethod = exports.createClientRegistry = exports.wrapClient = exports.toMeasurement = exports.entitlementRef = exports.entitlementKind = exports.entitlementId = exports.emptyTokenUsage = exports.vendorMetrics = exports.unitsPerTokens = exports.looksLikeGovernanceNotEnabled = exports.isGovernanceNotEnabled = exports.isAccessDenied = exports.isEngineError = exports.GovernanceNotEnabledError = exports.AccessDeniedError = exports.EngineError = exports.STIGG_TRACER_NAME = exports.noopLogger = exports.consoleLogger = exports.parseGovernanceHeaders = exports.GOVERNANCE_HEADERS = exports.remedyMessage = exports.describeDecision = exports.flattenRaw = exports.RAW_PREFIX = exports.StiggAgentSDK = void 0;
 /**
  * Public surface.
  *
@@ -123,6 +123,10 @@ Object.defineProperty(exports, "typesafeRecipe", { enumerable: true, get: functi
 Object.defineProperty(exports, "estimateFromState", { enumerable: true, get: function () { return typesafe_recipe_1.estimateFromState; } });
 var weighted_metrics_1 = require("./bindings/shared/weighted-metrics");
 Object.defineProperty(exports, "weightedMetrics", { enumerable: true, get: function () { return weighted_metrics_1.weightedMetrics; } });
+// The Vercel AI SDK binding (`ai` 6 and 7): a middleware for `wrapLanguageModel`. On the main entry
+// because it imports nothing from `ai` - a middleware is a plain object.
+var middleware_1 = require("./bindings/orchestrator/vercel-ai/middleware");
+Object.defineProperty(exports, "stiggVercelMiddleware", { enumerable: true, get: function () { return middleware_1.stiggVercelMiddleware; } });
 var token_usage_1 = require("./bindings/shared/token-usage");
 Object.defineProperty(exports, "normalizedMetrics", { enumerable: true, get: function () { return token_usage_1.normalizedMetrics; } });
 Object.defineProperty(exports, "normalizeUsage", { enumerable: true, get: function () { return token_usage_1.normalizeUsage; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigg/agent-sdk-js",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Stigg agent SDK (JS) - run-lifecycle governance for agentic stacks, with examples per layer",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
@@ -52,10 +52,12 @@
     "example-client-databricks": "tsx examples/client/databricks.ts",
     "example-client-typesafe": "tsx examples/client/typesafe.ts",
     "example-two-agents": "tsx examples/client/two-agents.ts",
-    "example-orchestrator-langchain": "tsx examples/orchestrator/langchain.ts",
-    "example-orchestrator-langgraph-handoff": "tsx examples/orchestrator/langgraph-handoff.ts",
-    "example-orchestrator-langgraph-model-fallback": "tsx examples/orchestrator/langgraph-model-fallback.ts",
-    "example-orchestrator-adk-handoff": "tsx examples/orchestrator/adk-handoff.ts",
+    "example-orchestrator-langchain": "tsx examples/orchestrator/langchain/langchain-handoff.ts",
+    "example-orchestrator-langgraph-handoff": "tsx examples/orchestrator/langchain/langgraph-handoff.ts",
+    "example-orchestrator-langgraph-model-fallback": "tsx examples/orchestrator/langchain/langgraph-model-fallback.ts",
+    "example-orchestrator-adk-handoff": "tsx examples/orchestrator/adk/adk-handoff.ts",
+    "example-orchestrator-adk-model-fallback": "tsx examples/orchestrator/adk/adk-model-fallback.ts",
+    "example-orchestrator-vercel-ai-handoff": "tsx examples/orchestrator/vercel-ai/vercel-ai-handoff.ts",
     "example-gateway": "tsx examples/gateway/openrouter.ts",
     "example-gateway-openrouter": "tsx examples/gateway/openrouter.ts",
     "example-gateway-litellm": "tsx examples/gateway/litellm.ts",
@@ -98,6 +100,7 @@
     }
   },
   "devDependencies": {
+    "@ai-sdk/anthropic": "^4.0.91",
     "@anthropic-ai/sdk": "^0.124.0",
     "@aws-sdk/client-bedrock-runtime": "^3.1150.0",
     "@databricks/sdk-modelservingquery": "0.25.0",
@@ -119,6 +122,7 @@
     "@opentelemetry/sdk-trace-base": "^2.12.0",
     "@opentelemetry/sdk-trace-node": "^2.0.1",
     "@typesafe-ai/sdk": "^0.6.0",
+    "ai": "^7.0.153",
     "cloudflare": "^7.3.0",
     "dotenv": "^17.4.2",
     "groq-sdk": "^1.6.0",