@polpo-ai/core 0.15.43 → 0.15.45

package/dist/guardrails/errors.d.ts

@@ -0,0 +1,17 @@
+import type { RuntimeGuardrailDecision } from "../runtime-plan/types.js";
+export declare class GuardrailError extends Error {
+    readonly decisions: readonly RuntimeGuardrailDecision[];
+    constructor(message: string, decisions?: readonly RuntimeGuardrailDecision[]);
+}
+export declare class GuardrailBlockedError extends GuardrailError {
+    readonly code = "guardrail_blocked";
+}
+export declare class GuardrailApprovalRequiredError extends GuardrailError {
+    readonly code = "guardrail_approval_required";
+}
+export declare class GuardrailAbortedError extends GuardrailError {
+    readonly code = "guardrail_aborted";
+    readonly outcomeUncertain: boolean;
+    constructor(message?: string, decisions?: readonly RuntimeGuardrailDecision[], outcomeUncertain?: boolean);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/guardrails/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/guardrails/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAEzE,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,SAAS,EAAE,SAAS,wBAAwB,EAAE,CAAC;gBAE5C,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,SAAS,wBAAwB,EAAO;CAKjF;AAED,qBAAa,qBAAsB,SAAQ,cAAc;IACvD,QAAQ,CAAC,IAAI,uBAAuB;CACrC;AAED,qBAAa,8BAA+B,SAAQ,cAAc;IAChE,QAAQ,CAAC,IAAI,iCAAiC;CAC/C;AAED,qBAAa,qBAAsB,SAAQ,cAAc;IACvD,QAAQ,CAAC,IAAI,uBAAuB;IACpC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;gBAGjC,OAAO,SAAqC,EAC5C,SAAS,GAAE,SAAS,wBAAwB,EAAO,EACnD,gBAAgB,UAAQ;CAK3B"}

package/dist/guardrails/errors.js

@@ -0,0 +1,23 @@
+export class GuardrailError extends Error {
+    decisions;
+    constructor(message, decisions = []) {
+        super(message);
+        this.name = new.target.name;
+        this.decisions = Object.freeze([...decisions]);
+    }
+}
+export class GuardrailBlockedError extends GuardrailError {
+    code = "guardrail_blocked";
+}
+export class GuardrailApprovalRequiredError extends GuardrailError {
+    code = "guardrail_approval_required";
+}
+export class GuardrailAbortedError extends GuardrailError {
+    code = "guardrail_aborted";
+    outcomeUncertain;
+    constructor(message = "Guardrail evaluation was aborted", decisions = [], outcomeUncertain = false) {
+        super(message, decisions);
+        this.outcomeUncertain = outcomeUncertain;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/guardrails/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/guardrails/errors.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,SAAS,CAAsC;IAExD,YAAY,OAAe,EAAE,YAAiD,EAAE;QAC9E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;IACjD,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,cAAc;IAC9C,IAAI,GAAG,mBAAmB,CAAC;CACrC;AAED,MAAM,OAAO,8BAA+B,SAAQ,cAAc;IACvD,IAAI,GAAG,6BAA6B,CAAC;CAC/C;AAED,MAAM,OAAO,qBAAsB,SAAQ,cAAc;IAC9C,IAAI,GAAG,mBAAmB,CAAC;IAC3B,gBAAgB,CAAU;IAEnC,YACE,OAAO,GAAG,kCAAkC,EAC5C,YAAiD,EAAE,EACnD,gBAAgB,GAAG,KAAK;QAExB,KAAK,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC1B,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;IAC3C,CAAC;CACF"}

package/dist/guardrails/index.d.ts

@@ -0,0 +1,8 @@
+export { GuardrailAbortedError, GuardrailApprovalRequiredError, GuardrailBlockedError, GuardrailError, } from "./errors.js";
+export { RuntimeGuardrailEngine } from "./engine.js";
+export { createBoundedValuePolicy, createCrossScopePolicy, createDefaultOutputGuardrailPolicies, createDefaultToolGuardrailPolicies, createDestructiveOperationPolicy, createPrivateNetworkPolicy, createSecretPatternPolicy, createToolArgumentsPolicy, } from "./detectors.js";
+export { createRunOutputPolicy } from "./output-policy.js";
+export { createObservationalRunToolMiddleware, createRunToolMiddleware, inferToolSideEffect, wrapRunToolExecutor, } from "./tool-middleware.js";
+export { createConfiguredRunToolMiddleware, createConfiguredRunOutputPolicy, normalizeRuntimeGuardrailSettings, } from "./settings.js";
+export type { RunToolExecutionResult, RunOutputPolicy, RunOutputPolicyOptions, RunOutputPolicyRequest, RunOutputPolicyResult, RunToolMiddleware, RunToolMiddlewareOptions, RunToolNext, RunToolRequest, RuntimeGuardrailApprovalHandler, RuntimeGuardrailApprovalResult, RuntimeGuardrailOutputApprovalHandler, RuntimeGuardrailAuditEvent, RuntimeGuardrailContext, RuntimeGuardrailEngineOptions, RuntimeGuardrailEvaluation, RuntimeGuardrailEvaluationInput, RuntimeGuardrailHostAdapters, RuntimeGuardrailPolicy, RuntimeGuardrailPolicyResult, RuntimeGuardrailSettings, RuntimeOutputEnforcementMode, RuntimeStreamingOutputMode, RuntimeGuardrailScope, RuntimeGuardrailToolContext, RuntimeToolSideEffect, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/guardrails/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guardrails/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,8BAA8B,EAC9B,qBAAqB,EACrB,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,oCAAoC,EACpC,kCAAkC,EAClC,gCAAgC,EAChC,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EACL,oCAAoC,EACpC,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,iCAAiC,EACjC,+BAA+B,EAC/B,iCAAiC,GAClC,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,sBAAsB,EACtB,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACxB,WAAW,EACX,cAAc,EACd,+BAA+B,EAC/B,8BAA8B,EAC9B,qCAAqC,EACrC,0BAA0B,EAC1B,uBAAuB,EACvB,6BAA6B,EAC7B,0BAA0B,EAC1B,+BAA+B,EAC/B,4BAA4B,EAC5B,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,EACxB,4BAA4B,EAC5B,0BAA0B,EAC1B,qBAAqB,EACrB,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/guardrails/index.js

@@ -0,0 +1,7 @@
+export { GuardrailAbortedError, GuardrailApprovalRequiredError, GuardrailBlockedError, GuardrailError, } from "./errors.js";
+export { RuntimeGuardrailEngine } from "./engine.js";
+export { createBoundedValuePolicy, createCrossScopePolicy, createDefaultOutputGuardrailPolicies, createDefaultToolGuardrailPolicies, createDestructiveOperationPolicy, createPrivateNetworkPolicy, createSecretPatternPolicy, createToolArgumentsPolicy, } from "./detectors.js";
+export { createRunOutputPolicy } from "./output-policy.js";
+export { createObservationalRunToolMiddleware, createRunToolMiddleware, inferToolSideEffect, wrapRunToolExecutor, } from "./tool-middleware.js";
+export { createConfiguredRunToolMiddleware, createConfiguredRunOutputPolicy, normalizeRuntimeGuardrailSettings, } from "./settings.js";
+//# sourceMappingURL=index.js.map

package/dist/guardrails/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/guardrails/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,8BAA8B,EAC9B,qBAAqB,EACrB,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,oCAAoC,EACpC,kCAAkC,EAClC,gCAAgC,EAChC,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EACL,oCAAoC,EACpC,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,iCAAiC,EACjC,+BAA+B,EAC/B,iCAAiC,GAClC,MAAM,eAAe,CAAC"}

package/dist/guardrails/output-policy.d.ts

@@ -0,0 +1,4 @@
+import { RuntimeGuardrailEngine } from "./engine.js";
+import type { RunOutputPolicy, RunOutputPolicyOptions } from "./types.js";
+export declare function createRunOutputPolicy(engine: RuntimeGuardrailEngine, options?: RunOutputPolicyOptions): RunOutputPolicy;
+//# sourceMappingURL=output-policy.d.ts.map

package/dist/guardrails/output-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-policy.d.ts","sourceRoot":"","sources":["../../src/guardrails/output-policy.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EACV,eAAe,EACf,sBAAsB,EAGvB,MAAM,YAAY,CAAC;AAQpB,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,sBAAsB,EAC9B,OAAO,GAAE,sBAA2B,GACnC,eAAe,CAmFjB"}

package/dist/guardrails/output-policy.js

@@ -0,0 +1,64 @@
+import { GuardrailAbortedError, GuardrailApprovalRequiredError, GuardrailBlockedError, } from "./errors.js";
+function terminalDecision(decisions) {
+    return decisions[decisions.length - 1];
+}
+export function createRunOutputPolicy(engine, options = {}) {
+    const streamingMode = options.streamingMode ?? "audit";
+    if (streamingMode !== "audit" && streamingMode !== "buffer") {
+        throw new TypeError('streamingMode must be "audit" or "buffer"');
+    }
+    return Object.freeze({
+        streamingMode,
+        async evaluate(request) {
+            if (typeof request.output !== "string") {
+                throw new TypeError("Guardrail output must be a string");
+            }
+            if (request.mode !== "enforce" && request.mode !== "audit") {
+                throw new TypeError('Guardrail output mode must be "enforce" or "audit"');
+            }
+            const evaluation = await engine.evaluate({
+                phase: "output",
+                value: request.output,
+                context: request.context,
+                signal: request.signal,
+            });
+            if (request.mode === "audit") {
+                return Object.freeze({
+                    output: request.output,
+                    decisions: evaluation.decisions,
+                    enforced: false,
+                });
+            }
+            if (evaluation.terminalAction === "block") {
+                throw new GuardrailBlockedError(terminalDecision(evaluation.decisions).reason, evaluation.decisions);
+            }
+            if (evaluation.terminalAction === "approval") {
+                const decision = terminalDecision(evaluation.decisions);
+                if (!options.approval) {
+                    throw new GuardrailApprovalRequiredError(decision.reason, evaluation.decisions);
+                }
+                const approval = await options.approval(Object.freeze({
+                    ...request,
+                    output: typeof evaluation.value === "string"
+                        ? evaluation.value
+                        : request.output,
+                }), decision);
+                if (request.signal?.aborted) {
+                    throw new GuardrailAbortedError("Guardrail output approval was interrupted", evaluation.decisions);
+                }
+                if (approval !== "approved") {
+                    throw new GuardrailBlockedError("Guardrail output approval was denied", evaluation.decisions);
+                }
+            }
+            if (typeof evaluation.value !== "string") {
+                throw new GuardrailBlockedError("Guardrail rewrote output to a non-string value", evaluation.decisions);
+            }
+            return Object.freeze({
+                output: evaluation.value,
+                decisions: evaluation.decisions,
+                enforced: true,
+            });
+        },
+    });
+}
+//# sourceMappingURL=output-policy.js.map

package/dist/guardrails/output-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-policy.js","sourceRoot":"","sources":["../../src/guardrails/output-policy.ts"],"names":[],"mappings":"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"}

package/dist/guardrails/settings.d.ts

@@ -0,0 +1,12 @@
+import type { RunOutputPolicy, RunToolMiddleware, RuntimeGuardrailHostAdapters, RuntimeGuardrailSettings } from "./types.js";
+export declare function normalizeRuntimeGuardrailSettings(value: unknown): RuntimeGuardrailSettings | undefined;
+/**
+ * Build the OSS deterministic policy pack from serializable host settings.
+ *
+ * Undefined settings are the off switch and return undefined. Host adapters
+ * remain process-local: audit and approval callbacks never enter persisted
+ * RunnerConfig data.
+ */
+export declare function createConfiguredRunToolMiddleware(value: RuntimeGuardrailSettings | undefined, adapters?: RuntimeGuardrailHostAdapters): RunToolMiddleware | undefined;
+export declare function createConfiguredRunOutputPolicy(value: RuntimeGuardrailSettings | undefined, adapters?: RuntimeGuardrailHostAdapters): RunOutputPolicy | undefined;
+//# sourceMappingURL=settings.d.ts.map

package/dist/guardrails/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/guardrails/settings.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,4BAA4B,EAC5B,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAEpB,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,OAAO,GACb,wBAAwB,GAAG,SAAS,CAiGtC;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,wBAAwB,GAAG,SAAS,EAC3C,QAAQ,GAAE,4BAAiC,GAC1C,iBAAiB,GAAG,SAAS,CAe/B;AAED,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,wBAAwB,GAAG,SAAS,EAC3C,QAAQ,GAAE,4BAAiC,GAC1C,eAAe,GAAG,SAAS,CAY7B"}

package/dist/guardrails/settings.js

@@ -0,0 +1,108 @@
+import { createDefaultOutputGuardrailPolicies, createDefaultToolGuardrailPolicies, } from "./detectors.js";
+import { RuntimeGuardrailEngine } from "./engine.js";
+import { createRunOutputPolicy } from "./output-policy.js";
+import { createRunToolMiddleware } from "./tool-middleware.js";
+export function normalizeRuntimeGuardrailSettings(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("guardrails must be an object");
+    }
+    const raw = value;
+    if (raw.toolPolicyPack === undefined
+        && raw.outputPolicyPack === undefined
+        && Object.keys(raw).length === 0) {
+        return undefined;
+    }
+    if (raw.toolPolicyPack !== undefined && raw.toolPolicyPack !== "default") {
+        throw new TypeError('guardrails.toolPolicyPack must be "default"');
+    }
+    if (raw.outputPolicyPack !== undefined && raw.outputPolicyPack !== "default") {
+        throw new TypeError('guardrails.outputPolicyPack must be "default"');
+    }
+    if (raw.toolPolicyPack === undefined && (raw.maxToolOutputCharacters !== undefined
+        || raw.readOnlyPolicyFailure !== undefined)) {
+        throw new TypeError("guardrails tool settings require guardrails.toolPolicyPack");
+    }
+    if (raw.outputPolicyPack === undefined && (raw.maxFinalOutputCharacters !== undefined
+        || raw.streamingOutputMode !== undefined)) {
+        const field = raw.streamingOutputMode !== undefined
+            ? "streamingOutputMode"
+            : "maxFinalOutputCharacters";
+        throw new TypeError(`guardrails.${field} requires guardrails.outputPolicyPack`);
+    }
+    if (raw.toolPolicyPack === undefined && raw.outputPolicyPack === undefined) {
+        return undefined;
+    }
+    let maxToolOutputCharacters;
+    if (raw.maxToolOutputCharacters !== undefined) {
+        if (!Number.isSafeInteger(raw.maxToolOutputCharacters) ||
+            raw.maxToolOutputCharacters < 1) {
+            throw new TypeError("guardrails.maxToolOutputCharacters must be a positive safe integer");
+        }
+        maxToolOutputCharacters = raw.maxToolOutputCharacters;
+    }
+    let readOnlyPolicyFailure;
+    if (raw.readOnlyPolicyFailure !== undefined) {
+        if (raw.readOnlyPolicyFailure !== "audit" && raw.readOnlyPolicyFailure !== "block") {
+            throw new TypeError('guardrails.readOnlyPolicyFailure must be "audit" or "block"');
+        }
+        readOnlyPolicyFailure = raw.readOnlyPolicyFailure;
+    }
+    let maxFinalOutputCharacters;
+    if (raw.maxFinalOutputCharacters !== undefined) {
+        if (!Number.isSafeInteger(raw.maxFinalOutputCharacters)
+            || raw.maxFinalOutputCharacters < 1) {
+            throw new TypeError("guardrails.maxFinalOutputCharacters must be a positive safe integer");
+        }
+        maxFinalOutputCharacters = raw.maxFinalOutputCharacters;
+    }
+    let streamingOutputMode;
+    if (raw.outputPolicyPack !== undefined) {
+        if (raw.streamingOutputMode !== undefined
+            && raw.streamingOutputMode !== "audit"
+            && raw.streamingOutputMode !== "buffer") {
+            throw new TypeError('guardrails.streamingOutputMode must be "audit" or "buffer"');
+        }
+        streamingOutputMode = (raw.streamingOutputMode ?? "audit");
+    }
+    return Object.freeze({
+        ...(raw.toolPolicyPack === "default" ? { toolPolicyPack: "default" } : {}),
+        ...(raw.outputPolicyPack === "default" ? { outputPolicyPack: "default" } : {}),
+        ...(maxToolOutputCharacters !== undefined ? { maxToolOutputCharacters } : {}),
+        ...(maxFinalOutputCharacters !== undefined ? { maxFinalOutputCharacters } : {}),
+        ...(readOnlyPolicyFailure !== undefined ? { readOnlyPolicyFailure } : {}),
+        ...(streamingOutputMode !== undefined ? { streamingOutputMode } : {}),
+    });
+}
+/**
+ * Build the OSS deterministic policy pack from serializable host settings.
+ *
+ * Undefined settings are the off switch and return undefined. Host adapters
+ * remain process-local: audit and approval callbacks never enter persisted
+ * RunnerConfig data.
+ */
+export function createConfiguredRunToolMiddleware(value, adapters = {}) {
+    const settings = normalizeRuntimeGuardrailSettings(value);
+    if (!settings?.toolPolicyPack)
+        return undefined;
+    const engine = new RuntimeGuardrailEngine(createDefaultToolGuardrailPolicies(), {
+        onDecision: adapters.onDecision,
+        readOnlyPolicyFailure: settings.readOnlyPolicyFailure,
+    });
+    return createRunToolMiddleware(engine, {
+        approval: adapters.approval,
+        maxOutputCharacters: settings.maxToolOutputCharacters,
+    });
+}
+export function createConfiguredRunOutputPolicy(value, adapters = {}) {
+    const settings = normalizeRuntimeGuardrailSettings(value);
+    if (!settings?.outputPolicyPack)
+        return undefined;
+    const engine = new RuntimeGuardrailEngine(createDefaultOutputGuardrailPolicies(settings.maxFinalOutputCharacters), { onDecision: adapters.onDecision });
+    return createRunOutputPolicy(engine, {
+        approval: adapters.outputApproval,
+        streamingMode: settings.streamingOutputMode,
+    });
+}
+//# sourceMappingURL=settings.js.map

package/dist/guardrails/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../../src/guardrails/settings.ts"],"names":[],"mappings":"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"}

package/dist/guardrails/tool-middleware.d.ts

@@ -0,0 +1,15 @@
+import { RuntimeGuardrailEngine } from "./engine.js";
+import type { RunToolMiddleware, RunToolMiddlewareOptions, RunToolRequest, RuntimeToolSideEffect } from "./types.js";
+export declare function inferToolSideEffect(name: string): RuntimeToolSideEffect;
+export declare function createRunToolMiddleware(engine: RuntimeGuardrailEngine, options?: RunToolMiddlewareOptions): RunToolMiddleware;
+/**
+ * Evaluate an enforcing middleware after the real tool call and retain only
+ * its secret-free decisions. The original arguments and output always win.
+ *
+ * Hosts use this for shadow/audit rollout modes. Policy failures are
+ * deliberately best-effort: observation must never change a successful tool
+ * execution.
+ */
+export declare function createObservationalRunToolMiddleware(configured: RunToolMiddleware): RunToolMiddleware;
+export declare function wrapRunToolExecutor(executor: (name: string, args: Record<string, unknown>) => Promise<string>, middleware: RunToolMiddleware | undefined, resolveRequest: (name: string, args: Record<string, unknown>) => Omit<RunToolRequest, "name" | "args"> & Partial<Pick<RunToolRequest, "name" | "args">>): (name: string, args: Record<string, unknown>) => Promise<string>;
+//# sourceMappingURL=tool-middleware.d.ts.map

package/dist/guardrails/tool-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-middleware.d.ts","sourceRoot":"","sources":["../../src/guardrails/tool-middleware.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAEV,iBAAiB,EACjB,wBAAwB,EAExB,cAAc,EACd,qBAAqB,EACtB,MAAM,YAAY,CAAC;AA6BpB,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,CAavE;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,sBAAsB,EAC9B,OAAO,GAAE,wBAA6B,GACrC,iBAAiB,CA4GnB;AAED;;;;;;;GAOG;AACH,wBAAgB,oCAAoC,CAClD,UAAU,EAAE,iBAAiB,GAC5B,iBAAiB,CAyBnB;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,EAC1E,UAAU,EAAE,iBAAiB,GAAG,SAAS,EACzC,cAAc,EAAE,CACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,GAC1F,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAclE"}

package/dist/guardrails/tool-middleware.js

@@ -0,0 +1,158 @@
+import { GuardrailError, GuardrailAbortedError, GuardrailApprovalRequiredError, GuardrailBlockedError, } from "./errors.js";
+const DEFAULT_MAX_OUTPUT_CHARACTERS = 256_000;
+function freezeArgs(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new GuardrailBlockedError("Guardrail rewrote tool arguments to a non-object value");
+    }
+    return value;
+}
+function normalizeOutput(output, maxCharacters) {
+    const normalized = output.replace(/\r\n?/g, "\n");
+    if (normalized.length <= maxCharacters)
+        return { output: normalized, truncated: false };
+    let bounded = normalized.slice(0, maxCharacters);
+    const finalCode = bounded.charCodeAt(bounded.length - 1);
+    if (finalCode >= 0xd800 && finalCode <= 0xdbff)
+        bounded = bounded.slice(0, -1);
+    return { output: `${bounded}\n[TRUNCATED]`, truncated: true };
+}
+function terminalDecision(decisions) {
+    return decisions[decisions.length - 1];
+}
+export function inferToolSideEffect(name) {
+    const normalized = name.trim().toLowerCase().replace(/^mcp__[^_]+__/, "");
+    if (/^(get|list|read|search|find|inspect|describe|query|fetch|download|view|stat|check|lookup|count)(_|$)/.test(normalized)) {
+        return "read";
+    }
+    if (/^(create|add|set|update|edit|write|delete|remove|send|deploy|publish|run|execute|bash|shell|upload|move|copy|rename|approve|reject)(_|$)/.test(normalized)) {
+        return "write";
+    }
+    return "unknown";
+}
+export function createRunToolMiddleware(engine, options = {}) {
+    const maxOutputCharacters = options.maxOutputCharacters ?? DEFAULT_MAX_OUTPUT_CHARACTERS;
+    if (!Number.isSafeInteger(maxOutputCharacters) || maxOutputCharacters < 1) {
+        throw new TypeError("maxOutputCharacters must be a positive safe integer");
+    }
+    return {
+        async execute(request, next) {
+            if (request.signal?.aborted)
+                throw new GuardrailAbortedError();
+            const normalizedRequest = Object.freeze({
+                ...request,
+                sideEffect: request.sideEffect ?? inferToolSideEffect(request.name),
+            });
+            const before = await engine.evaluate({
+                phase: "tool.before",
+                value: request.args,
+                context: request.context,
+                tool: {
+                    name: request.name,
+                    callId: request.callId,
+                    sideEffect: normalizedRequest.sideEffect,
+                    schema: request.schema,
+                },
+                signal: request.signal,
+            });
+            const args = freezeArgs(before.value);
+            if (before.terminalAction === "block") {
+                throw new GuardrailBlockedError(terminalDecision(before.decisions).reason, before.decisions);
+            }
+            if (before.terminalAction === "approval") {
+                const decision = terminalDecision(before.decisions);
+                if (!options.approval) {
+                    throw new GuardrailApprovalRequiredError(decision.reason, before.decisions);
+                }
+                const approval = await options.approval(Object.freeze({ ...normalizedRequest, args }), decision);
+                if (request.signal?.aborted) {
+                    throw new GuardrailAbortedError(undefined, before.decisions);
+                }
+                if (approval !== "approved") {
+                    throw new GuardrailBlockedError("Guardrail approval was denied", before.decisions);
+                }
+            }
+            const toolRequest = Object.freeze({ ...normalizedRequest, args });
+            const rawOutput = await next(toolRequest);
+            if (typeof rawOutput !== "string") {
+                throw new TypeError(`Tool "${request.name}" returned a non-string result`);
+            }
+            if (request.signal?.aborted) {
+                throw new GuardrailAbortedError("Tool execution was aborted after dispatch; the outcome may be uncertain", before.decisions, normalizedRequest.sideEffect !== "read");
+            }
+            const bounded = normalizeOutput(rawOutput, maxOutputCharacters);
+            const after = await engine.evaluate({
+                phase: "tool.after",
+                value: bounded.output,
+                context: request.context,
+                tool: {
+                    name: request.name,
+                    callId: request.callId,
+                    sideEffect: normalizedRequest.sideEffect,
+                    schema: request.schema,
+                },
+                signal: request.signal,
+                outputTruncated: bounded.truncated,
+            });
+            const decisions = Object.freeze([...before.decisions, ...after.decisions]);
+            if (after.terminalAction === "block") {
+                throw new GuardrailBlockedError(terminalDecision(after.decisions).reason, decisions);
+            }
+            if (after.terminalAction === "approval") {
+                throw new GuardrailApprovalRequiredError("Approval cannot be deferred until after a tool has executed", decisions);
+            }
+            if (typeof after.value !== "string") {
+                throw new GuardrailBlockedError("Guardrail rewrote tool output to a non-string value", decisions);
+            }
+            return Object.freeze({
+                output: after.value,
+                args,
+                decisions,
+                outputTruncated: bounded.truncated,
+            });
+        },
+    };
+}
+/**
+ * Evaluate an enforcing middleware after the real tool call and retain only
+ * its secret-free decisions. The original arguments and output always win.
+ *
+ * Hosts use this for shadow/audit rollout modes. Policy failures are
+ * deliberately best-effort: observation must never change a successful tool
+ * execution.
+ */
+export function createObservationalRunToolMiddleware(configured) {
+    return Object.freeze({
+        async execute(request, next) {
+            const output = await next(request);
+            let decisions = [];
+            try {
+                const evaluation = await configured.execute(request, async () => output);
+                decisions = evaluation.decisions;
+            }
+            catch (error) {
+                if (error instanceof GuardrailError)
+                    decisions = error.decisions;
+            }
+            return Object.freeze({
+                output,
+                args: request.args,
+                decisions: Object.freeze([...decisions]),
+                outputTruncated: false,
+            });
+        },
+    });
+}
+export function wrapRunToolExecutor(executor, middleware, resolveRequest) {
+    if (!middleware)
+        return executor;
+    return async (name, args) => {
+        const request = resolveRequest(name, args);
+        const result = await middleware.execute({
+            ...request,
+            name: request.name ?? name,
+            args: request.args ?? args,
+        }, (nextRequest) => executor(nextRequest.name, nextRequest.args));
+        return result.output;
+    };
+}
+//# sourceMappingURL=tool-middleware.js.map

package/dist/guardrails/tool-middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-middleware.js","sourceRoot":"","sources":["../../src/guardrails/tool-middleware.ts"],"names":[],"mappings":"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"}

package/dist/guardrails/types.d.ts

@@ -0,0 +1,148 @@
+import type { RuntimeGuardrailAction, RuntimeGuardrailDecision, RuntimeGuardrailPhase, RuntimeGuardrailRisk, RuntimeInvocationSource, RuntimeSurface } from "../runtime-plan/types.js";
+export type RuntimeToolSideEffect = "read" | "write" | "unknown";
+export interface RuntimeGuardrailScope {
+    readonly expected?: Readonly<Record<string, string | undefined>>;
+    readonly actual?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Host-neutral guardrail context. Hosts may attach identifiers used for
+ * auditing and scope comparison, but must never place credentials here.
+ */
+export interface RuntimeGuardrailContext {
+    readonly planId?: string;
+    readonly surface?: RuntimeSurface;
+    readonly source?: RuntimeInvocationSource;
+    readonly agent?: string;
+    readonly runId?: string;
+    readonly sessionId?: string;
+    readonly scope?: RuntimeGuardrailScope;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface RuntimeGuardrailToolContext {
+    readonly name: string;
+    readonly callId?: string;
+    readonly sideEffect: RuntimeToolSideEffect;
+    readonly schema?: unknown;
+}
+export interface RuntimeGuardrailEvaluationInput<T = unknown> {
+    readonly phase: RuntimeGuardrailPhase;
+    readonly value: T;
+    readonly context: RuntimeGuardrailContext;
+    readonly tool?: RuntimeGuardrailToolContext;
+    readonly signal?: AbortSignal;
+    readonly outputTruncated?: boolean;
+}
+export interface RuntimeGuardrailPolicyResult<T = unknown> {
+    readonly action: RuntimeGuardrailAction;
+    readonly risk: RuntimeGuardrailRisk;
+    readonly reason: string;
+    /**
+     * Required for redact/rewrite. The engine passes this value to subsequent
+     * policies and, eventually, the guarded operation.
+     */
+    readonly value?: T;
+    readonly fallbackUsed?: boolean;
+}
+export interface RuntimeGuardrailPolicy<T = unknown> {
+    readonly id: string;
+    readonly version?: string;
+    readonly priority?: number;
+    readonly phases: readonly RuntimeGuardrailPhase[];
+    evaluate(input: RuntimeGuardrailEvaluationInput<T>): RuntimeGuardrailPolicyResult<T> | null | Promise<RuntimeGuardrailPolicyResult<T> | null>;
+}
+export interface RuntimeGuardrailEvaluation<T = unknown> {
+    readonly value: T;
+    readonly decisions: readonly RuntimeGuardrailDecision[];
+    readonly terminalAction?: Extract<RuntimeGuardrailAction, "block" | "approval">;
+}
+export interface RuntimeGuardrailAuditEvent {
+    readonly decision: RuntimeGuardrailDecision;
+    readonly context: RuntimeGuardrailContext;
+    readonly tool?: Readonly<{
+        name: string;
+        callId?: string;
+        sideEffect: RuntimeToolSideEffect;
+    }>;
+    readonly outputTruncated?: boolean;
+}
+export interface RuntimeGuardrailEngineOptions {
+    readonly createId?: () => string;
+    readonly now?: () => number;
+    /**
+     * Secret-free decision sink. The evaluated value and tool schema are
+     * intentionally excluded from the event.
+     */
+    readonly onDecision?: (event: RuntimeGuardrailAuditEvent) => void | Promise<void>;
+    readonly readOnlyPolicyFailure?: "audit" | "block";
+}
+export interface RunToolRequest {
+    readonly callId?: string;
+    readonly name: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly schema?: unknown;
+    readonly sideEffect?: RuntimeToolSideEffect;
+    readonly context: RuntimeGuardrailContext;
+    readonly signal?: AbortSignal;
+}
+export type RunToolNext = (request: RunToolRequest) => Promise<string>;
+export interface RunToolExecutionResult {
+    readonly output: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly decisions: readonly RuntimeGuardrailDecision[];
+    readonly outputTruncated: boolean;
+}
+export type RuntimeGuardrailApprovalResult = "approved" | "denied";
+export type RuntimeGuardrailApprovalHandler = (request: RunToolRequest, decision: RuntimeGuardrailDecision) => RuntimeGuardrailApprovalResult | Promise<RuntimeGuardrailApprovalResult>;
+export interface RunToolMiddleware {
+    execute(request: RunToolRequest, next: RunToolNext): Promise<RunToolExecutionResult>;
+}
+export interface RunToolMiddlewareOptions {
+    readonly approval?: RuntimeGuardrailApprovalHandler;
+    /** Maximum tool-result content characters evaluated and returned to the model. */
+    readonly maxOutputCharacters?: number;
+}
+export type RuntimeOutputEnforcementMode = "enforce" | "audit";
+export type RuntimeStreamingOutputMode = "audit" | "buffer";
+export interface RunOutputPolicyRequest {
+    readonly output: string;
+    readonly mode: RuntimeOutputEnforcementMode;
+    readonly context: RuntimeGuardrailContext;
+    readonly signal?: AbortSignal;
+}
+export interface RunOutputPolicyResult {
+    readonly output: string;
+    readonly decisions: readonly RuntimeGuardrailDecision[];
+    /** False means the output was already delivered and decisions are observational. */
+    readonly enforced: boolean;
+}
+export type RuntimeGuardrailOutputApprovalHandler = (request: RunOutputPolicyRequest, decision: RuntimeGuardrailDecision) => RuntimeGuardrailApprovalResult | Promise<RuntimeGuardrailApprovalResult>;
+export interface RunOutputPolicy {
+    readonly streamingMode: RuntimeStreamingOutputMode;
+    evaluate(request: RunOutputPolicyRequest): Promise<RunOutputPolicyResult>;
+}
+export interface RunOutputPolicyOptions {
+    readonly approval?: RuntimeGuardrailOutputApprovalHandler;
+    readonly streamingMode?: RuntimeStreamingOutputMode;
+}
+/**
+ * Serializable, host-neutral settings that may cross a process boundary in a
+ * RunnerConfig. The absent setting is deliberately the disabled state.
+ */
+export interface RuntimeGuardrailSettings {
+    readonly toolPolicyPack?: "default";
+    readonly outputPolicyPack?: "default";
+    readonly maxToolOutputCharacters?: number;
+    readonly maxFinalOutputCharacters?: number;
+    readonly readOnlyPolicyFailure?: "audit" | "block";
+    readonly streamingOutputMode?: RuntimeStreamingOutputMode;
+}
+/**
+ * Process-local adapters. These callbacks are never persisted in settings or
+ * RunnerConfig and therefore remain the responsibility of the active host.
+ */
+export interface RuntimeGuardrailHostAdapters {
+    readonly approval?: RuntimeGuardrailApprovalHandler;
+    readonly outputApproval?: RuntimeGuardrailOutputApprovalHandler;
+    readonly onDecision?: RuntimeGuardrailEngineOptions["onDecision"];
+}
+//# sourceMappingURL=types.d.ts.map