promptguard-sdk 2.2.1 → 2.4.0

package/dist/integrations/vercel-ai-output.js

@@ -0,0 +1,330 @@
+"use strict";
+/**
+ * Output scanning for the Vercel AI SDK integration — generated and streamed.
+ *
+ * This is the one place that decides what a model's output is scanned as and
+ * what a decision about it does. The middleware (`vercel-ai.ts`) calls it from
+ * both `wrapGenerate` and `wrapStream`, and anything else that wraps an AI SDK
+ * model should call it too rather than restating the policy.
+ *
+ * Streams are scanned in windows, then once more in full:
+ *
+ * - **Enforce mode** holds back the stream parts that carry scanned text
+ *   (text deltas, tool-call input) until that text has been scanned. Each
+ *   time `windowChars` new characters have arrived, everything held is
+ *   scanned and, if clean, released — except the last `WINDOW_OVERLAP_CHARS`
+ *   characters, which stay held and are scanned again at the head of the next
+ *   window. So every released character has been scanned together with at
+ *   least the overlap that follows it, and a secret up to the overlap long is
+ *   always seen whole before any of it is released. When the model finishes,
+ *   the complete text is scanned — the same text, built the same way, as a
+ *   generated result — before the held tail and the `finish` part are
+ *   released. Parts that carry no scanned text (stream start, reasoning,
+ *   sources, files, metadata) are delivered at once when nothing is held
+ *   ahead of them, and queue behind held text otherwise, so order is kept.
+ * - **Monitor mode** never stops a call, so it never holds one: parts pass
+ *   through as they arrive and only the complete text is scanned, at the end.
+ *
+ * Reasoning is not scanned, here or on the generated path.
+ *
+ * A block (or an output redact, which cannot be honoured on text already
+ * generated) stops the stream with `PromptGuardBlockedError`. A Guard API
+ * outage fails open by default (ADR-0002): the held parts are released and the
+ * rest of that stream passes unscanned, so an outage costs one failed scan per
+ * stream rather than one per window. With `failOpen: false` it stops the
+ * stream with the `GuardApiError` instead.
+ *
+ * How a stopped stream ends is the caller's choice (`StreamStop`): by
+ * erroring it, so whatever reads it throws, or by delivering one AI SDK
+ * `error` part and closing it. Either way nothing held is released and the
+ * `finish` part never arrives.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WINDOW_OVERLAP_CHARS = exports.DEFAULT_STREAM_WINDOW_CHARS = void 0;
+exports.validateWindowChars = validateWindowChars;
+exports.scanOutputText = scanOutputText;
+exports.extractGeneratedText = extractGeneratedText;
+exports.scanOutputStream = scanOutputStream;
+const guard_1 = require("../guard");
+const logger_1 = require("../logger");
+/**
+ * Default new characters of streamed output per scanned window.
+ *
+ * Not taken from any external standard: 1000 was chosen as a balance between
+ * how long output is held and how many Guard API round trips a stream costs.
+ * At roughly four characters a token it is about 250 tokens, which takes a
+ * model a few seconds to generate — about as long as one Guard round trip, so
+ * scanning a window roughly keeps pace with generating the next. A smaller
+ * window delivers the first text sooner and costs more scans; a larger one
+ * costs fewer scans and holds output longer.
+ */
+exports.DEFAULT_STREAM_WINDOW_CHARS = 1000;
+/**
+ * Characters of scanned text always kept held and rescanned at the head of
+ * the next window — the longest secret guaranteed to be seen whole across a
+ * window boundary.
+ */
+exports.WINDOW_OVERLAP_CHARS = 200;
+/** Throws `RangeError` unless `value` is a usable `streamWindowChars`. */
+function validateWindowChars(value) {
+    if (!(value > 0)) {
+        throw new RangeError(`streamWindowChars must be a positive number, got ${value}`);
+    }
+    return value;
+}
+/**
+ * Scan one piece of model output. Resolves when the output may be delivered;
+ * throws `PromptGuardBlockedError` when enforce mode stops it, and rethrows
+ * the `GuardApiError` when failing closed. `sessionId` names the
+ * Conversation the call belongs to, when it names one.
+ */
+async function scanOutputText(text, policy, modelId, what = "response", sessionId) {
+    try {
+        const decision = await policy.guard.scan([{ role: "assistant", content: text }], "output", modelId, { framework: "vercel-ai-sdk", ...(sessionId !== undefined ? { sessionId } : {}) });
+        if (decision.blocked || decision.redacted) {
+            // Generated output cannot be rewritten after the fact, so an
+            // output-direction redact decision is enforced as a block.
+            if (policy.mode === "enforce")
+                throw new guard_1.PromptGuardBlockedError(decision);
+            logger_1.logger.warn(`[monitor] would ${decision.redacted ? "redact" : "block"} ${what}: ${decision.threatType}`);
+        }
+        return "scanned";
+    }
+    catch (err) {
+        if (err instanceof guard_1.PromptGuardBlockedError)
+            throw err;
+        // Only a Guard API outage is eligible for fail-open; rethrow the
+        // original error when failing closed.
+        if (!(err instanceof guard_1.GuardApiError))
+            throw err;
+        if (!policy.failOpen)
+            throw err;
+        logger_1.logger.warn(`Guard API unavailable, ${what} left unscanned (failOpen=true): ${(0, guard_1.safeErrorLabel)(err)}`);
+        return "failed-open";
+    }
+}
+/**
+ * Extract all scannable text from a `doGenerate` result.
+ *
+ * Handles both AI SDK result shapes:
+ *  - **v4 (LanguageModelV1):** top-level `text` string plus `toolCalls`
+ *    (every tool call's `args`/`input` is scanned — not just the first).
+ *  - **v5+ (LanguageModelV2/V3):** `content` is an array of parts
+ *    (`{ type: "text", text }` / `{ type: "tool-call", input }`) with no
+ *    top-level `text`.
+ *
+ * Returns the concatenated text, or `null` when nothing scannable exists.
+ */
+function extractGeneratedText(result) {
+    const texts = [];
+    const stringify = (value) => typeof value === "string" ? value : JSON.stringify(value);
+    if (typeof result?.text === "string" && result.text)
+        texts.push(result.text);
+    if (Array.isArray(result?.content)) {
+        for (const raw of result.content) {
+            if (!raw || typeof raw !== "object")
+                continue;
+            const part = raw;
+            if (part.type === "text" && typeof part.text === "string" && part.text) {
+                texts.push(part.text);
+            }
+            else if (part.type === "tool-call") {
+                const args = part.input ?? part.args;
+                if (args != null)
+                    texts.push(stringify(args));
+            }
+        }
+    }
+    if (Array.isArray(result?.toolCalls)) {
+        for (const raw of result.toolCalls) {
+            if (!raw || typeof raw !== "object")
+                continue;
+            const call = raw;
+            const args = call.args ?? call.input;
+            if (args != null)
+                texts.push(stringify(args));
+        }
+    }
+    const combined = texts.join("\n");
+    return combined || null;
+}
+/**
+ * Accumulates a model stream's parts into the result `doGenerate` would have
+ * returned, so the final scan sees exactly what a generated response would.
+ *
+ * Recognises both stream-part vocabularies:
+ *  - **LanguageModelV1:** `text-delta { textDelta }`,
+ *    `tool-call-delta { toolCallId, argsTextDelta }`, `tool-call { args }`.
+ *  - **LanguageModelV2/V3:** `text-delta { id, delta }`,
+ *    `tool-input-delta { id, delta }`, `tool-call { toolCallId, input }`.
+ */
+class StreamedOutput {
+    constructor() {
+        /** Text blocks by id, in first-seen order (V1 parts have no id). */
+        this.texts = new Map();
+        /** Tool input assembled from deltas, by call id. */
+        this.toolDeltas = new Map();
+        /** Complete tool calls, by call id. */
+        this.toolCalls = new Map();
+    }
+    /**
+     * Record one part. Returns the newly visible text it carries (for the
+     * window), or `""` when it carries none.
+     */
+    add(part) {
+        switch (part.type) {
+            case "text-delta": {
+                const delta = str(part.delta) ?? str(part.textDelta) ?? "";
+                const id = str(part.id) ?? "";
+                this.texts.set(id, (this.texts.get(id) ?? "") + delta);
+                return delta;
+            }
+            case "tool-input-delta":
+            case "tool-call-delta": {
+                const delta = str(part.delta) ?? str(part.argsTextDelta) ?? "";
+                const id = str(part.id) ?? str(part.toolCallId) ?? "";
+                this.toolDeltas.set(id, (this.toolDeltas.get(id) ?? "") + delta);
+                return delta;
+            }
+            case "tool-call": {
+                const id = str(part.toolCallId) ?? "";
+                const input = part.input ?? part.args;
+                if (input == null)
+                    return "";
+                this.toolCalls.set(id, input);
+                // Input already streamed as deltas was counted when it arrived.
+                if (this.toolDeltas.has(id))
+                    return "";
+                return typeof input === "string" ? input : JSON.stringify(input);
+            }
+            default:
+                return "";
+        }
+    }
+    /** The complete output, as `extractGeneratedText` renders a generated result. */
+    text() {
+        const content = [];
+        for (const text of this.texts.values())
+            content.push({ type: "text", text });
+        for (const [id, input] of this.toolCalls)
+            content.push({ type: "tool-call", toolCallId: id, input });
+        // A call streamed as deltas whose closing `tool-call` part never came.
+        for (const [id, input] of this.toolDeltas) {
+            if (!this.toolCalls.has(id))
+                content.push({ type: "tool-call", toolCallId: id, input });
+        }
+        return extractGeneratedText({ content });
+    }
+}
+function str(value) {
+    return typeof value === "string" ? value : undefined;
+}
+/**
+ * Wrap a model stream so its output is scanned as described in this module's
+ * header. Parts are passed through unchanged and in order; where the policy
+ * stops the output, the stream ends with `PromptGuardBlockedError` (or the
+ * `GuardApiError` when failing closed), as `stopAs` says.
+ */
+function scanOutputStream(stream, policy, modelId, stopAs = "error", sessionId) {
+    const output = new StreamedOutput();
+    const enforce = policy.mode === "enforce";
+    const what = "streamed response";
+    /** Held parts, in order, with the scanned text each carries. */
+    let held = [];
+    /** Total length of the text carried by `held`. */
+    let heldChars = 0;
+    /** Characters that have arrived since the last window scan. */
+    let unscannedChars = 0;
+    /** Set once fail-open has given up on this stream. */
+    let unscanned = false;
+    /** Set once the stream has ended with an error part. */
+    let stopped = false;
+    const releaseAll = (controller) => {
+        for (const { part } of held)
+            controller.enqueue(part);
+        held = [];
+        heldChars = 0;
+    };
+    /** Release from the front while the overlap stays held behind it. */
+    const releaseScanned = (controller) => {
+        while (held.length && heldChars - held[0].text.length >= exports.WINDOW_OVERLAP_CHARS) {
+            const front = held.shift();
+            heldChars -= front.text.length;
+            controller.enqueue(front.part);
+        }
+    };
+    return stream.pipeThrough(new TransformStream({
+        async transform(part, controller) {
+            if (stopped)
+                return;
+            try {
+                await step(part, controller);
+            }
+            catch (err) {
+                stop(err, controller);
+                // Ends the stream here, and cancels the model's stream behind it.
+                controller.terminate();
+            }
+        },
+        async flush(controller) {
+            if (stopped)
+                return;
+            try {
+                await finish(controller);
+            }
+            catch (err) {
+                stop(err, controller);
+            }
+        },
+    }));
+    /** End a stopped stream as `stopAs` says. */
+    function stop(err, controller) {
+        if (stopAs === "error")
+            throw err;
+        stopped = true;
+        controller.enqueue({ type: "error", error: err });
+    }
+    async function step(part, controller) {
+        if (unscanned) {
+            controller.enqueue(part);
+            return;
+        }
+        const record = part && typeof part === "object" ? part : null;
+        const text = record ? output.add(record) : "";
+        if (!enforce) {
+            controller.enqueue(part);
+            return;
+        }
+        // Nothing to scan and nothing ahead of it: no reason to hold it. The
+        // finish part always waits for the final scan.
+        if (!text && !held.length && record?.type !== "finish") {
+            controller.enqueue(part);
+            return;
+        }
+        held.push({ part, text });
+        heldChars += text.length;
+        unscannedChars += text.length;
+        if (unscannedChars < policy.windowChars)
+            return;
+        unscannedChars = 0;
+        const window = held.map((h) => h.text).join("");
+        // Throws on block or fail-closed, which stops the stream (see `stop`).
+        const outcome = await scanOutputText(window, policy, modelId, `rest of ${what}`, sessionId);
+        if (outcome === "scanned") {
+            releaseScanned(controller);
+        }
+        else {
+            unscanned = true;
+            releaseAll(controller);
+        }
+    }
+    async function finish(controller) {
+        if (unscanned)
+            return;
+        const text = output.text();
+        if (text)
+            await scanOutputText(text, policy, modelId, what, sessionId);
+        releaseAll(controller);
+    }
+}
+//# sourceMappingURL=vercel-ai-output.js.map

package/dist/integrations/vercel-ai-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel-ai-output.js","sourceRoot":"","sources":["../../src/integrations/vercel-ai-output.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;;;AAkCH,kDAKC;AAeD,wCAkCC;AAcD,oDAkCC;AAqFD,4CA+GC;AA1UD,oCAAmG;AACnG,sCAAkC;AAElC;;;;;;;;;;GAUG;AACU,QAAA,2BAA2B,GAAG,IAAI,CAAA;AAE/C;;;;GAIG;AACU,QAAA,oBAAoB,GAAG,GAAG,CAAA;AAUvC,0EAA0E;AAC1E,SAAgB,mBAAmB,CAAC,KAAa;IAC/C,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;QACjB,MAAM,IAAI,UAAU,CAAC,oDAAoD,KAAK,EAAE,CAAC,CAAA;IACnF,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AASD;;;;;GAKG;AACI,KAAK,UAAU,cAAc,CAClC,IAAY,EACZ,MAAwB,EACxB,OAA2B,EAC3B,IAAI,GAAG,UAAU,EACjB,SAAkB;IAElB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,CACtC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EACtC,QAAQ,EACR,OAAO,EACP,EAAE,SAAS,EAAE,eAAe,EAAE,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAClF,CAAA;QACD,IAAI,QAAQ,CAAC,OAAO,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;YAC1C,6DAA6D;YAC7D,2DAA2D;YAC3D,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;gBAAE,MAAM,IAAI,+BAAuB,CAAC,QAAQ,CAAC,CAAA;YAC1E,eAAM,CAAC,IAAI,CACT,mBAAmB,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,IAAI,IAAI,KAAK,QAAQ,CAAC,UAAU,EAAE,CAC5F,CAAA;QACH,CAAC;QACD,OAAO,SAAS,CAAA;IAClB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,+BAAuB;YAAE,MAAM,GAAG,CAAA;QACrD,iEAAiE;QACjE,sCAAsC;QACtC,IAAI,CAAC,CAAC,GAAG,YAAY,qBAAa,CAAC;YAAE,MAAM,GAAG,CAAA;QAC9C,IAAI,CAAC,MAAM,CAAC,QAAQ;YAAE,MAAM,GAAG,CAAA;QAC/B,eAAM,CAAC,IAAI,CACT,0BAA0B,IAAI,oCAAoC,IAAA,sBAAc,EAAC,GAAG,CAAC,EAAE,CACxF,CAAA;QACD,OAAO,aAAa,CAAA;IACtB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,oBAAoB,CAClC,MAAkD;IAElD,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,MAAM,SAAS,GAAG,CAAC,KAAc,EAAU,EAAE,CAC3C,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;IAE3D,IAAI,OAAO,MAAM,EAAE,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAE5E,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;QACnC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACjC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;gBAAE,SAAQ;YAC7C,MAAM,IAAI,GAAG,GAA8B,CAAA;YAC3C,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACvE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YACvB,CAAC;iBAAM,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;gBACrC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,CAAA;gBACpC,IAAI,IAAI,IAAI,IAAI;oBAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAA;YAC/C,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC;QACrC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACnC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;gBAAE,SAAQ;YAC7C,MAAM,IAAI,GAAG,GAA8B,CAAA;YAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,CAAA;YACpC,IAAI,IAAI,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAA;QAC/C,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACjC,OAAO,QAAQ,IAAI,IAAI,CAAA;AACzB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,cAAc;IAApB;QACE,oEAAoE;QACnD,UAAK,GAAG,IAAI,GAAG,EAAkB,CAAA;QAClD,oDAAoD;QACnC,eAAU,GAAG,IAAI,GAAG,EAAkB,CAAA;QACvD,uCAAuC;QACtB,cAAS,GAAG,IAAI,GAAG,EAAmB,CAAA;IA+CzD,CAAC;IA7CC;;;OAGG;IACH,GAAG,CAAC,IAA6B;QAC/B,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,KAAK,YAAY,CAAC,CAAC,CAAC;gBAClB,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAA;gBAC1D,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAA;gBAC7B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,KAAK,CAAC,CAAA;gBACtD,OAAO,KAAK,CAAA;YACd,CAAC;YACD,KAAK,kBAAkB,CAAC;YACxB,KAAK,iBAAiB,CAAC,CAAC,CAAC;gBACvB,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAA;gBAC9D,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAA;gBACrD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,KAAK,CAAC,CAAA;gBAChE,OAAO,KAAK,CAAA;YACd,CAAC;YACD,KAAK,WAAW,CAAC,CAAC,CAAC;gBACjB,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAA;gBACrC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,CAAA;gBACrC,IAAI,KAAK,IAAI,IAAI;oBAAE,OAAO,EAAE,CAAA;gBAC5B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAA;gBAC7B,gEAAgE;gBAChE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBAAE,OAAO,EAAE,CAAA;gBACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;YAClE,CAAC;YACD;gBACE,OAAO,EAAE,CAAA;QACb,CAAC;IACH,CAAC;IAED,iFAAiF;IACjF,IAAI;QACF,MAAM,OAAO,GAA8B,EAAE,CAAA;QAC7C,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE;YAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;QAC5E,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,SAAS;YACtC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;QAC5D,uEAAuE;QACvE,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC1C,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;QACzF,CAAC;QACD,OAAO,oBAAoB,CAAC,EAAE,OAAO,EAAE,CAAC,CAAA;IAC1C,CAAC;CACF;AAED,SAAS,GAAG,CAAC,KAAc;IACzB,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AACtD,CAAC;AAUD;;;;;GAKG;AACH,SAAgB,gBAAgB,CAC9B,MAAyB,EACzB,MAAwB,EACxB,OAA2B,EAC3B,SAAqB,OAAO,EAC5B,SAAkB;IAElB,MAAM,MAAM,GAAG,IAAI,cAAc,EAAE,CAAA;IACnC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,KAAK,SAAS,CAAA;IACzC,MAAM,IAAI,GAAG,mBAAmB,CAAA;IAEhC,gEAAgE;IAChE,IAAI,IAAI,GAAgC,EAAE,CAAA;IAC1C,kDAAkD;IAClD,IAAI,SAAS,GAAG,CAAC,CAAA;IACjB,+DAA+D;IAC/D,IAAI,cAAc,GAAG,CAAC,CAAA;IACtB,sDAAsD;IACtD,IAAI,SAAS,GAAG,KAAK,CAAA;IACrB,wDAAwD;IACxD,IAAI,OAAO,GAAG,KAAK,CAAA;IAEnB,MAAM,UAAU,GAAG,CAAC,UAA+C,EAAE,EAAE;QACrE,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,IAAI;YAAE,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QACrD,IAAI,GAAG,EAAE,CAAA;QACT,SAAS,GAAG,CAAC,CAAA;IACf,CAAC,CAAA;IAED,qEAAqE;IACrE,MAAM,cAAc,GAAG,CAAC,UAA+C,EAAE,EAAE;QACzE,OAAO,IAAI,CAAC,MAAM,IAAI,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,IAAI,4BAAoB,EAAE,CAAC;YAC9E,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAA+B,CAAA;YACvD,SAAS,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,CAAA;YAC9B,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QAChC,CAAC;IACH,CAAC,CAAA;IAED,OAAO,MAAM,CAAC,WAAW,CACvB,IAAI,eAAe,CAAO;QACxB,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,UAAU;YAC9B,IAAI,OAAO;gBAAE,OAAM;YACnB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;YAC9B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAA;gBACrB,kEAAkE;gBAClE,UAAU,CAAC,SAAS,EAAE,CAAA;YACxB,CAAC;QACH,CAAC;QAED,KAAK,CAAC,KAAK,CAAC,UAAU;YACpB,IAAI,OAAO;gBAAE,OAAM;YACnB,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,UAAU,CAAC,CAAA;YAC1B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAA;YACvB,CAAC;QACH,CAAC;KACF,CAAC,CACH,CAAA;IAED,6CAA6C;IAC7C,SAAS,IAAI,CAAC,GAAY,EAAE,UAA+C;QACzE,IAAI,MAAM,KAAK,OAAO;YAAE,MAAM,GAAG,CAAA;QACjC,OAAO,GAAG,IAAI,CAAA;QACd,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAO,CAAC,CAAA;IACxD,CAAC;IAED,KAAK,UAAU,IAAI,CAAC,IAAO,EAAE,UAA+C;QAC1E,IAAI,SAAS,EAAE,CAAC;YACd,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;YACxB,OAAM;QACR,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAE,IAAgC,CAAC,CAAC,CAAC,IAAI,CAAA;QAC1F,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;QAE7C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;YACxB,OAAM;QACR,CAAC;QAED,qEAAqE;QACrE,+CAA+C;QAC/C,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,MAAM,EAAE,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;YACxB,OAAM;QACR,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;QACzB,SAAS,IAAI,IAAI,CAAC,MAAM,CAAA;QACxB,cAAc,IAAI,IAAI,CAAC,MAAM,CAAA;QAC7B,IAAI,cAAc,GAAG,MAAM,CAAC,WAAW;YAAE,OAAM;QAE/C,cAAc,GAAG,CAAC,CAAA;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAC/C,uEAAuE;QACvE,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,IAAI,EAAE,EAAE,SAAS,CAAC,CAAA;QAC3F,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,cAAc,CAAC,UAAU,CAAC,CAAA;QAC5B,CAAC;aAAM,CAAC;YACN,SAAS,GAAG,IAAI,CAAA;YAChB,UAAU,CAAC,UAAU,CAAC,CAAA;QACxB,CAAC;IACH,CAAC;IAED,KAAK,UAAU,MAAM,CAAC,UAA+C;QACnE,IAAI,SAAS;YAAE,OAAM;QACrB,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAA;QAC1B,IAAI,IAAI;YAAE,MAAM,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,CAAA;QACtE,UAAU,CAAC,UAAU,CAAC,CAAA;IACxB,CAAC;AACH,CAAC"}

package/dist/integrations/vercel-ai.d.ts

@@ -1,29 +1,65 @@
 /**
- * Vercel AI SDK integration - middleware for `ai` package.
+ * Vercel AI SDK integration for the `ai` package.
  *
- * Works with the Vercel AI SDK's `wrapLanguageModel` API to intercept
- * all model calls with PromptGuard security scanning.
+ * Two ways in, with the same scanning:
+ *
+ * - `promptguard(model)` wraps a language model of ai 5, 6 or 7
+ *   (specification v2, v3 or v4), and the wrapped model is used wherever the
+ *   original was:
  *
- * @example
  * ```ts
  * import { openai } from '@ai-sdk/openai';
- * import { wrapLanguageModel, generateText } from 'ai';
+ * import { generateText } from 'ai';
+ * import { promptguard } from 'promptguard-sdk/integrations/vercel-ai';
+ *
+ * const model = promptguard(openai('gpt-5-nano'), { scanResponses: true });
+ * const { text } = await generateText({ model, prompt: 'Hello!' });
+ * ```
+ *
+ * - `promptGuardMiddleware(options)` is the same scanning as AI SDK
+ *   middleware, for `wrapLanguageModel` — useful alongside other middleware,
+ *   and the way in on ai 4:
+ *
+ * ```ts
+ * import { wrapLanguageModel } from 'ai';
  * import { promptGuardMiddleware } from 'promptguard-sdk/integrations/vercel-ai';
  *
  * const model = wrapLanguageModel({
  *   model: openai('gpt-5-nano'),
  *   middleware: promptGuardMiddleware({ apiKey: 'pg_live_xxx' }),
  * });
- *
- * const { text } = await generateText({ model, prompt: 'Hello!' });
  * ```
+ *
+ * With `scanResponses: true`, `streamText()` output is scanned too: in
+ * enforce mode text is held until it has been scanned, a window
+ * (`streamWindowChars`, default 1000 characters) at a time, and the complete
+ * text is scanned before the stream finishes. See `vercel-ai-output.ts` for
+ * the full behaviour and its guarantee.
+ *
+ * Neither imports `ai`: the wrapper calls the middleware's hooks the way
+ * `wrapLanguageModel` does, so it works with whichever `ai` the application
+ * has (ai@7 is ESM-only; this package is CommonJS) and loads without one.
  */
 import { type GuardClientConfig } from "../guard";
 import { type LogLevel } from "../logger";
-export interface PromptGuardMiddlewareOptions extends GuardClientConfig {
+export interface PromptGuardMiddlewareOptions extends Omit<GuardClientConfig, "apiKey"> {
+    /** PromptGuard API key (default: the `PROMPTGUARD_API_KEY` environment variable). */
+    apiKey?: string;
     mode?: "enforce" | "monitor";
+    /**
+     * Scan the model's output as well as its input (default: `false`). Applies
+     * to `generateText()` and to `streamText()` alike.
+     */
     scanResponses?: boolean;
     failOpen?: boolean;
+    /**
+     * With `scanResponses` in enforce mode, how many new characters of
+     * streamed output are collected before the held text is scanned (default:
+     * `1000`; see `DEFAULT_STREAM_WINDOW_CHARS` for why). A smaller window
+     * delivers the first text sooner at the cost of more scans; `Infinity`
+     * holds the whole response for a single scan at the end.
+     */
+    streamWindowChars?: number;
     /**
      * SDK log verbosity (default: `"warn"`). Set to `"silent"` to suppress logs.
      * NOTE: this sets the **process-global** SDK log level (shared with `init()`
@@ -32,36 +68,90 @@ export interface PromptGuardMiddlewareOptions extends GuardClientConfig {
     logLevel?: LogLevel;
     /** Convenience shorthand for `logLevel: "silent"`. */
     silent?: boolean;
+    /**
+     * The Conversation to name when a call names none of its own. The AI SDK
+     * has no conversation id, so a call names one with
+     * `providerOptions: { promptguard: { sessionId } }` (`providerMetadata` on
+     * `ai@4`), which wins over this. Without either, no session id is sent.
+     */
+    sessionId?: string;
 }
 /**
  * Create a Vercel AI SDK middleware that scans inputs/outputs via
  * the PromptGuard Guard API.
  *
  * Returns an object conforming to the Vercel AI SDK `LanguageModelMiddleware`
- * interface (`transformParams` + `wrapGenerate`).
+ * interface (`transformParams`, plus `wrapGenerate` and `wrapStream` when
+ * `scanResponses` is set). The hooks are generic over the call options and
+ * results they pass through, so the object is assignable to the middleware
+ * type of each supported `ai` major (checked by `tests/vercel-ai-types.test.ts`).
  */
-export declare function promptGuardMiddleware(options: PromptGuardMiddlewareOptions): {
+export declare function promptGuardMiddleware(options?: PromptGuardMiddlewareOptions): {
+    /**
+     * The middleware specification version. ai@6 requires `"v3"` here;
+     * ai@7 accepts any version string, and ai@5 does not read it. The hooks
+     * themselves read every call shape from V2 to V4.
+     */
+    specificationVersion: "v3";
     /**
      * transformParams - scans the input messages before they reach the model.
      */
-    transformParams: ({ params }: {
-        params: Record<string, unknown>;
-    }) => Promise<Record<string, unknown>>;
+    transformParams: <P extends object>({ params, model, }: {
+        params: P;
+        model?: ModelIdentity;
+    }) => Promise<P>;
     /**
      * wrapGenerate - optionally scans the model's response.
      */
-    wrapGenerate: (({ doGenerate, params, }: {
-        doGenerate: () => Promise<unknown>;
-        params: Record<string, unknown>;
-    }) => Promise<unknown>) | undefined;
+    wrapGenerate: (<R>({ doGenerate, params, model, }: {
+        doGenerate: () => PromiseLike<R>;
+        params?: object;
+        model?: ModelIdentity;
+    }) => Promise<R>) | undefined;
     /**
-     * wrapStream - streamed outputs are NOT scanned (chunks are consumed
-     * incrementally by the caller and cannot be buffered without breaking
-     * stream semantics). Present only to log the skip so the gap is never
-     * silent; input scanning via transformParams still applies.
+     * wrapStream - optionally scans the model's streamed response, in
+     * windows and then in full, with the same decisions and the same
+     * fail-open policy as wrapGenerate (see `vercel-ai-output.ts`).
      */
-    wrapStream: (({ doStream }: {
-        doStream: () => Promise<unknown>;
-    }) => Promise<unknown>) | undefined;
+    wrapStream: (<R>({ doStream, params, model, }: {
+        doStream: () => PromiseLike<R>;
+        params?: object;
+        model?: ModelIdentity;
+    }) => Promise<R>) | undefined;
 };
+/**
+ * What every AI SDK language model specification (V1 to V4) has in common,
+ * which is all `promptguard()` relies on.
+ */
+export interface LanguageModelLike {
+    readonly specificationVersion: string;
+    readonly modelId: string;
+    doGenerate(options: never): PromiseLike<unknown>;
+    doStream(options: never): PromiseLike<unknown>;
+}
+/**
+ * Wrap an AI SDK language model so every call it makes is scanned by
+ * PromptGuard, exactly as `promptGuardMiddleware(options)` would scan it
+ * under `wrapLanguageModel` — generated and streamed alike.
+ *
+ * The wrapped model is the model it wraps in every other respect: its own
+ * specification version, provider, model id, supported URLs and any other
+ * property, so it is accepted wherever the original was and has the same
+ * type. Options are the middleware's; the API key defaults to
+ * `PROMPTGUARD_API_KEY`, and a missing one throws here rather than on the
+ * first call.
+ *
+ * @example
+ * ```ts
+ * const model = promptguard(openai('gpt-5-nano'), { scanResponses: true });
+ * const result = streamText({ model, prompt: 'Hello!' });
+ * ```
+ */
+export declare function promptguard<M extends LanguageModelLike>(model: M, options?: PromptGuardMiddlewareOptions): M;
+/** What the hooks read from the model `wrapLanguageModel` hands them. */
+interface ModelIdentity {
+    readonly specificationVersion?: unknown;
+    readonly modelId?: unknown;
+}
+export {};
 //# sourceMappingURL=vercel-ai.d.ts.map

package/dist/integrations/vercel-ai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vercel-ai.d.ts","sourceRoot":"","sources":["../../src/integrations/vercel-ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAGL,KAAK,iBAAiB,EAIvB,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,KAAK,QAAQ,EAAuB,MAAM,WAAW,CAAA;AAO9D,MAAM,WAAW,4BAA6B,SAAQ,iBAAiB;IACrE,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAMD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B;IAkBvE;;OAEG;kCACiC;QAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE;IAuEvE;;OAEG;6CAKI;QACD,UAAU,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;QAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAChC;IAyCL;;;;;OAKG;gCAEsB;QAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE;EAMhE"}
+{"version":3,"file":"vercel-ai.d.ts","sourceRoot":"","sources":["../../src/integrations/vercel-ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAGL,KAAK,iBAAiB,EAIvB,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,KAAK,QAAQ,EAAuB,MAAM,WAAW,CAAA;AAiB9D,MAAM,WAAW,4BAA6B,SAAQ,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAC;IACrF,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IAC5B;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,4BAAiC;IA2B5E;;;;OAIG;;IAGH;;OAEG;sBACqB,CAAC,SAAS,MAAM,sBAGrC;QACD,MAAM,EAAE,CAAC,CAAA;QACT,KAAK,CAAC,EAAE,aAAa,CAAA;KACtB,KAAG,OAAO,CAAC,CAAC,CAAC;IAoEd;;OAEG;oBAEQ,CAAC,kCAIL;QACD,UAAU,EAAE,MAAM,WAAW,CAAC,CAAC,CAAC,CAAA;QAChC,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,KAAK,CAAC,EAAE,aAAa,CAAA;KACtB,KAAG,OAAO,CAAC,CAAC,CAAC;IAiBlB;;;;OAIG;kBAEQ,CAAC,gCAIL;QACD,QAAQ,EAAE,MAAM,WAAW,CAAC,CAAC,CAAC,CAAA;QAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,KAAK,CAAC,EAAE,aAAa,CAAA;KACtB,KAAG,OAAO,CAAC,CAAC,CAAC;EAuBrB;AAyBD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,UAAU,CAAC,OAAO,EAAE,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;IAChD,QAAQ,CAAC,OAAO,EAAE,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;CAC/C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,iBAAiB,EACrD,KAAK,EAAE,CAAC,EACR,OAAO,GAAE,4BAAiC,GACzC,CAAC,CA+DH;AAgBD,yEAAyE;AACzE,UAAU,aAAa;IACrB,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAA;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAC3B"}