@stigg/agent-sdk-js 0.7.7 → 0.7.8

package/README.md

@@ -165,7 +165,7 @@ request.
 | | Orchestrator | | Orchestrator |
 | --- | --- | --- | --- |
 | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/langchain.svg" width="18" alt=""> | [LangChain](docs/langchain.md) | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/langgraph.svg" width="18" alt=""> | [LangGraph](docs/langchain.md#a-hand-built-langgraph) |
-| <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/google-adk.png" width="18" alt=""> | [Google ADK](docs/guide.md#google-adk-one-plugin-per-runner) | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/vercel.svg" width="18" alt=""> | [Vercel AI SDK](docs/vercel-ai.md) (model calls, for now) |
+| <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/google-adk.png" width="18" alt=""> | [Google ADK](docs/guide.md#google-adk-one-plugin-per-runner) | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/vercel.svg" width="18" alt=""> | [Vercel AI SDK](docs/vercel-ai.md) |
 | | Your own harness, through `stigg.middleware()` | | |
 
 Each binding is written against the *shape a vendor returns*, not against its SDK — so installing
@@ -187,7 +187,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 Vercel AI SDK model or agent ([guide](docs/vercel-ai.md)) | `wrapLanguageModel({ model, middleware: stiggVercelMiddleware({ stigg, stiggContext, tools }) })`, a call's own in `providerOptions.stigg`; paid tools through `middleware.tools(...)` |
 | 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/vercel-ai/middleware.d.ts

@@ -9,16 +9,26 @@
  * 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.
+ *
+ * A model middleware never sees a tool run, so the paid tools are governed by `tools()`, which wraps
+ * each one's `execute`. A tool call is governed as the model step that asked for it.
  */
 import type { StiggAgentSDK } from '../../../stigg-agent-sdk';
 import type { SessionHooks } from '../../../core/session';
-import type { ClientContext, GovernedAgentMiddleware, Measurement } from '../../../types';
+import type { ClientContext, GovernedAgentMiddleware, Measurement, MiddlewareTools } from '../../../types';
+import { type ModelUsage } from './usage';
 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;
+    /**
+     * The paid tools, by tool name - `'*'` for every tool not named, `false` to exempt one. Governed
+     * once wrapped by `tools()`. A sub-agent run inside a tool is metered by its own model calls, so
+     * give it `false` under `'*'`.
+     */
+    tools?: MiddlewareTools;
     hooks?: SessionHooks;
 };
 /**
@@ -40,13 +50,30 @@ export type StiggVercelMiddleware = {
         params: any;
         model?: any;
     }): Promise<any>;
+    /**
+     * The same tools, each paid one's `execute` wrapped: checked before it runs, and reported after it
+     * succeeds. A refused tool does not run; it fails with a message that names the tool and why, and
+     * `stigg.denial(error)` returns the decision. Tools with no `execute` are returned as they are.
+     */
+    tools<T extends Record<string, any>>(tools: T): T;
     /** What this middleware did, and what is still in flight. */
     readonly stigg: GovernedAgentMiddleware['stigg'];
 };
-export declare function stiggVercelMiddleware({ stigg, stiggContext, hooks, }: StiggVercelMiddlewareOptions): StiggVercelMiddleware;
+export declare function stiggVercelMiddleware({ stigg, stiggContext, tools: toolConfig, hooks, }: StiggVercelMiddlewareOptions): StiggVercelMiddleware;
+type StreamPart = {
+    type?: string;
+    id?: string;
+    modelId?: unknown;
+    delta?: unknown;
+    usage?: ModelUsage;
+};
 /**
  * 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, modelId?: string) => void): void;
+export declare function observeStream(result: any, signal: AbortSignal | undefined, done: (measurement: Measurement | undefined, modelId?: string) => void, 
+/** Each part, before the AI SDK reads it - so a tool call is known before its tool can start. */
+onPart?: (part: StreamPart & {
+    toolCallId?: unknown;
+}) => void): void;

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

@@ -3,17 +3,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.measurementOf = exports.VERCEL_AI_METRICS = void 0;
 exports.stiggVercelMiddleware = stiggVercelMiddleware;
 exports.observeStream = observeStream;
+const errors_1 = require("../../../errors");
+const hooks_1 = require("../../../core/hooks");
+const agent_middleware_1 = require("../core/agent-middleware");
 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, }) {
+/** How many asked-for tool calls are remembered. One that never runs - a client-side tool - is dropped past it. */
+const ISSUED_CALLS_LIMIT = 1_000;
+function stiggVercelMiddleware({ stigg, stiggContext, tools: toolConfig, 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 });
+    const governance = stigg.middleware({ stiggContext, tools: toolConfig, 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();
@@ -27,11 +32,128 @@ function stiggVercelMiddleware({ stigg, stiggContext, hooks, }) {
     // 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]);
+    const defaultCall = JSON.stringify([stiggContext?.customerId, stiggContext?.agentId]);
+    const callOf = (params) => contexts.get(params) ?? defaultCall;
+    /** Waits for a call's stream reports in flight, so its next check sees their spend. */
+    const settle = (call) => Promise.all(reporting.get(call) ?? []);
+    // A tool's `execute` is handed only the call id, so each tool call a model step asks for is kept
+    // by its id - before the AI SDK can start the tool - and taken when it runs.
+    // Only for tools `tools()` wrapped: another's call - client-side, run by the provider - never runs
+    // here, and would only fill the map.
+    // ponytail: keyed by the provider's id alone. First-party providers make each id unique; a
+    // backend that reuses ids (`call_0`) across concurrent calls would let one call's entry replace
+    // another's - scope the key by call if one shows up. A call `experimental_repairToolCall` renames
+    // is not kept either, and is governed as one no step asked for.
+    const issued = new Map();
+    const wrapped = new Set();
+    const ask = (params, part) => {
+        if (part?.type !== 'tool-call' || typeof part.toolCallId !== 'string' || part.providerExecuted)
+            return;
+        if (typeof part.toolName !== 'string' || !wrapped.has(part.toolName))
+            return;
+        issued.delete(part.toolCallId);
+        issued.set(part.toolCallId, { context: contexts.get(params), call: callOf(params) });
+        if (issued.size > ISSUED_CALLS_LIMIT)
+            issued.delete(issued.keys().next().value);
+    };
+    /**
+     * Said once per tool: a call no model step of this middleware asked for - approved after a pause
+     * (`needsApproval` runs it at the start of the next call, before any model step), answered on
+     * another instance, or asked by another middleware's model - and whose own context names no
+     * `stigg`, is governed by this middleware's own `stiggContext`, and reported for its customer.
+     */
+    const warned = new Set();
+    const warnOnce = (name) => {
+        if (warned.has(name))
+            return;
+        warned.add(name);
+        // A logger that throws must not fail the tool it only reports on.
+        (0, hooks_1.safely)(() => stigg.config?.logger?.warn(`[stigg] tool "${name}" ran without a model step this middleware saw asking for it, and its ` +
+            "context names no `stigg`, so it is governed by the middleware's own stiggContext. An approved " +
+            `tool does this: name its customer in \`toolsContext: { ${name}: { stigg: { customerId } } }\`.`), () => undefined);
+    };
+    /** Checks a tool call as the step that asked for it. Refused: an error the model may read. */
+    const startTool = async (name, input, options) => {
+        const callId = typeof options?.toolCallId === 'string' ? options.toolCallId : undefined;
+        const issuedCall = callId === undefined ? undefined : issued.get(callId);
+        if (callId !== undefined)
+            issued.delete(callId);
+        // No model step asked for it here - an approved tool runs at the start of the next call - so
+        // the tool's own context may name who it is for: `toolsContext` (ai 7), `experimental_context` (ai 6).
+        const stated = issuedCall ? undefined : toolContextOf(options);
+        const asked = issuedCall ?? (stated ? { context: stated, call: stated } : undefined);
+        if (!asked)
+            warnOnce(name);
+        // A stream reports when it ends, and the AI SDK runs its tools before that: the tool's check
+        // waits, so it sees the spend of the step that asked for it.
+        await settle(asked?.call ?? defaultCall);
+        const runId = `${prefix}:tool:${++steps}`;
+        try {
+            await governance.startTool(runId, { name, callId, input }, { stiggContexts: asked?.context ? [asked.context] : [] });
+        }
+        catch (err) {
+            const decision = (0, errors_1.isAccessDenied)(err);
+            if (!decision)
+                throw err;
+            // The AI SDK hands a failed tool's message to the model, so it says why, not who refused or
+            // what is left. The decision rides along as the cause, for `stigg.denial(error)`.
+            throw new Error(`${name} is not available: ${decision.reason ?? 'access denied'}.`, { cause: err });
+        }
+        return runId;
+    };
+    /**
+     * A tool whose `execute` is checked and reported. An `async function*` streams its results, and is
+     * reported by its last one, as the AI SDK takes it.
+     * ponytail: any other function returns a promise here, since the check is awaited first - so an
+     * async iterable it returns is run to its end and answered by its last value, without the
+     * preliminary results. Write it as `async function*` to stream them.
+     */
+    const governTool = (name, tool) => {
+        const execute = tool.execute;
+        if (Object.prototype.toString.call(execute) === '[object AsyncGeneratorFunction]') {
+            return async function* (input, options) {
+                const runId = await startTool(name, input, options);
+                let output;
+                let finished = false;
+                try {
+                    for await (const value of execute.call(tool, input, options)) {
+                        output = value;
+                        yield value;
+                    }
+                    finished = true;
+                }
+                finally {
+                    if (!finished)
+                        governance.abandon(runId);
+                }
+                await governance.endTool(runId, output, name);
+            };
+        }
+        return async (input, options) => {
+            const runId = await startTool(name, input, options);
+            let output;
+            try {
+                output = await execute.call(tool, input, options);
+                if (isAsyncIterable(output)) {
+                    let last;
+                    for await (const value of output)
+                        last = value;
+                    output = last;
+                }
+            }
+            catch (err) {
+                governance.abandon(runId);
+                throw err;
+            }
+            // Awaited, and the AI SDK waits for every tool before the next step: that step's check sees it.
+            await governance.endTool(runId, output, name);
+            return output;
+        };
+    };
     /** Checks the step, as the agent and customer this call names. Refused: `AccessDeniedError`. */
     const start = async (params, model, 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)) ?? []);
+        await settle(callOf(params));
         const runId = `${prefix}:${++steps}`;
         const context = contexts.get(params);
         // Kept by the middleware until the step ends, so the model the reply names can still land on it.
@@ -42,6 +164,23 @@ function stiggVercelMiddleware({ stigg, stiggContext, hooks, }) {
     return {
         specificationVersion: 'v3',
         stigg: governance.stigg,
+        tools(tools) {
+            if (!toolConfig || Object.keys(toolConfig).length === 0) {
+                throw new Error("stiggVercelMiddleware's tools() needs a `tools` option: the paid tools by name, '*' for the rest.");
+            }
+            // Only a tool the config governs - by name, else through `'*'` - as the core looks it up. An
+            // exempt or unpriced one is left as it is: nothing would check it, so nothing should wait.
+            const governed = (name) => {
+                const entry = Object.hasOwn(toolConfig, name) ? toolConfig[name] : toolConfig[agent_middleware_1.ALL_TOOLS];
+                return entry !== undefined && entry !== false;
+            };
+            return Object.fromEntries(Object.entries(tools).map(([name, tool]) => {
+                if (typeof tool?.execute !== 'function' || !governed(name))
+                    return [name, tool];
+                wrapped.add(name);
+                return [name, { ...tool, execute: governTool(name, tool) }];
+            }));
+        },
         async transformParams({ params }) {
             const options = params?.providerOptions;
             if (!options || typeof options !== 'object' || !('stigg' in options))
@@ -71,6 +210,8 @@ function stiggVercelMiddleware({ stigg, stiggContext, hooks, }) {
             const responseId = result?.response?.id;
             const chars = (0, usage_1.contentChars)(result?.content);
             served(trace, result?.response?.modelId);
+            for (const part of Array.isArray(result?.content) ? result.content : [])
+                ask(params, part);
             await governance.endModel(runId, (0, usage_1.measurementOf)(result?.usage, responseId) ?? (chars ? (0, usage_1.estimated)(chars, usage_1.NO_USAGE, responseId) : undefined));
             return result;
         },
@@ -98,7 +239,7 @@ function stiggVercelMiddleware({ stigg, stiggContext, hooks, }) {
                     if (pending.size === 0 && reporting.get(call) === pending)
                         reporting.delete(call);
                 });
-            });
+            }, (part) => ask(params, part));
             return result;
         },
     };
@@ -180,7 +321,9 @@ function streamTally() {
  * 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) {
+function observeStream(result, signal, done, 
+/** Each part, before the AI SDK reads it - so a tool call is known before its tool can start. */
+onPart) {
     const source = result?.stream;
     if (typeof source?.getReader !== 'function') {
         done(undefined);
@@ -214,6 +357,11 @@ function observeStream(result, signal, done) {
                 return;
             }
             tally.record(next.value);
+            onPart?.(next.value);
+            // The AI SDK starts a step's tools on its `finish` part, before the stream closes - which, from
+            // an HTTP provider, is a later read. So the step reports here, and its tools' checks see it.
+            if (next.value?.type === 'finish')
+                report('ended');
             controller.enqueue(next.value);
         },
         async cancel(reason) {
@@ -222,3 +370,17 @@ function observeStream(result, signal, done) {
         },
     });
 }
+const isAsyncIterable = (value) => typeof value?.[Symbol.asyncIterator] === 'function';
+/** The `stigg` a tool's own context states - its `toolsContext` entry on ai 7, `experimental_context` on ai 6. */
+function toolContextOf(options) {
+    const context = options?.context?.stigg ?? options?.experimental_context?.stigg;
+    if (context === undefined || context === null)
+        return undefined;
+    if (typeof context !== 'object' || Array.isArray(context)) {
+        throw new TypeError(`A tool's context \`stigg\` must be a stiggContext object - got ${typeof context}.`);
+    }
+    // On ai 6 the context is the whole app's, and `stigg` there may be the SDK instance itself: only
+    // a plain object is a stiggContext. Anything else names no one, and the SDK says so.
+    const proto = Object.getPrototypeOf(context);
+    return proto === Object.prototype || proto === null ? context : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigg/agent-sdk-js",
-  "version": "0.7.7",
+  "version": "0.7.8",
   "description": "Stigg agent SDK (JS) - run-lifecycle governance for agentic stacks, with examples per layer",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",