Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
feature/Template-refusal-securityerror · L-260929-75ff75 (#1440)
Louis Choquel03839b2d249d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1d5d9dede..e9c4414f1 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,11 @@# Changelog+## [Unreleased]++### Changed++- **`Jinja2TemplateSecurityError` is a `SecurityError` (Breaking)**: the template sandbox's refusal at render time now derives from `SecurityError`, like `UriReadRefusedError`, `SsrfBlockedError` and `UnsafeSchemaError`, instead of `ToolError`, so a host catching `SecurityError` catches it too and an `except ToolError` no longer does; it stays a type of its own, apart from `Jinja2TemplateRenderError`, and its `error_type`, title and classification are unchanged.+## [v0.89.0] - 2026-10-17### Addeddiff --git a/docs/errors/jinja2-template-security-error.md b/docs/errors/jinja2-template-security-error.mdindex 0f80b0d9d..be5cd4879 100644--- a/docs/errors/jinja2-template-security-error.md+++ b/docs/errors/jinja2-template-security-error.md@@ -14,6 +14,6 @@ description: "Reference for the `Jinja2TemplateSecurityError` Pipelex error clas| `type_uri` | `https://docs.pipelex.com/latest/errors/jinja2-template-security-error/` || `error_domain` | _(inherited from parent)_ || Defined in | `pipelex.tools.jinja2.exceptions` |-| Parent class | [`ToolError`](tool-error.md) |+| Parent class | [`SecurityError`](security-error.md) |[Back to Error Reference](index.md)diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.mdindex 16e46ca8e..38d988607 100644--- a/docs/under-the-hood/error-model.md+++ b/docs/under-the-hood/error-model.md@@ -486,6 +486,10 @@ Exception└── PipelexError base_exceptions.py — error_domain, user_action, to_error_report()├── PipelexConfigError → error_domain = CONFIG├── PipelexSetupError → error_domain = CONFIG+ ├── SecurityError base_exceptions.py — the policy refusals never absorbed into a domain answer+ │ ├── UriReadRefusedError / SsrfBlockedError → error_domain = INPUT, caller-facing message+ │ ├── UnsafeSchemaError+ │ └── Jinja2TemplateSecurityError ← the template sandbox's refusal at render time├── CogtError cogt/exceptions.py — error_category, provider_metadata│ │ → error_domain derived from error_category (no per-class declaration)│ ├── LLMCompletionError ← per-instance category from the worker → per-instance domain@@ -500,6 +504,8 @@ Exception└── ... (one exceptions.py per package) ...```+`SecurityError` is the base class of the policy refusals that are never absorbed into a domain answer: `UriReadRefusedError` (a read outside the run's scope), `SsrfBlockedError` (an outbound request the SSRF guard blocks), `UnsafeSchemaError` (a schema carrying Python code-generation extensions) and `Jinja2TemplateSecurityError` (a template the sandbox refuses at render time). The handlers that turn a refusal of the caller's input into a verdict, the bundle-validation cascade and the library load, let a `SecurityError` through as it is, and a host that treats this family alike, a durable-execution plugin marking it non-retryable for instance, names that base class. Not every refusal belongs to it: the template sandbox's render-budget refusal, `Jinja2TemplateBudgetError`, is a `ToolError` in the `input` domain, and `TemplateUrlRefusedError` derives from `PipelexError` directly, also in the `input` domain, so each is handled by its domain like any other refusal of the caller's input.+`PipelineExecutionError`'s `RUNTIME` is deliberately a *floor*, applied only when the cause chain surfaced no domain — so a `CONTENT`-categorized inference failure now reaches the HTTP boundary as `INPUT` / 422 through every wrapping layer instead of being flattened to the wrapper's generic 500. Its identity and message are its root fault's (see [Run Failures: the Root Fault, Located](#run-failures-the-root-fault-located)).### Factory-time vs Runtimediff --git a/docs/under-the-hood/template-sandbox.md b/docs/under-the-hood/template-sandbox.mdindex 56f631521..7f35e043e 100644--- a/docs/under-the-hood/template-sandbox.md+++ b/docs/under-the-hood/template-sandbox.md@@ -44,6 +44,8 @@ Many refusals are visible in the template itself, and validation reports them beWhat validation cannot see, because it depends on the values at run time (a method call, a name computed while rendering, or a bracketed key, which is legitimate on a plain dict), is refused where it happens: the render raises [`Jinja2TemplateSecurityError`](../errors/jinja2-template-security-error.md), whose message names the refused attribute or callable and the type it was reached on. A refusal never renders as an empty string, so a prompt is never sent with a hole in it.+`Jinja2TemplateSecurityError` is a [`SecurityError`](../errors/security-error.md), like `UriReadRefusedError`, `SsrfBlockedError` and `UnsafeSchemaError`, the other policy refusals that are never absorbed into a domain answer. A host that treats that family alike, never retrying any of it, catches that base class, and an `except ToolError` around a render does not catch this refusal. The sandbox's budget refusal is a separate error, `Jinja2TemplateBudgetError`, which is a `ToolError` in the input domain (see below). `Jinja2TemplateSecurityError` stays a type of its own, apart from `Jinja2TemplateRenderError`, which a template that fails for any other reason raises.+A render that would overdraw its budget raises [`Jinja2TemplateBudgetError`](../errors/jinja2-template-budget-error.md), in the input domain, whose message names the operation that was refused and what it would have spent, never the template or a value: for example, *the operator '\*' needs about 1,000,000,000, and 134,217,062 are left*. A template whose macros or includes nest deeper than Python allows raises the same error.## How it is builtdiff --git a/pipelex/tools/jinja2/exceptions.py b/pipelex/tools/jinja2/exceptions.pyindex 331a1d2f6..ef63f80ad 100644--- a/pipelex/tools/jinja2/exceptions.py+++ b/pipelex/tools/jinja2/exceptions.py@@ -1,4 +1,4 @@-from pipelex.base_exceptions import ErrorDomain+from pipelex.base_exceptions import ErrorDomain, SecurityErrorfrom pipelex.system.exceptions import ToolError@@ -15,11 +15,13 @@ class Jinja2TemplateRenderError(ToolError):pass-class Jinja2TemplateSecurityError(ToolError):+class Jinja2TemplateSecurityError(SecurityError):# A template reached for something the sandbox policy refuses (`jinja2_sandbox.py`): an undeclared# private name, or a call that is not a method of a plain value. Its message names the attribute or# the callable and the type it was reached on, and never quotes the template source, since the same- # render serves Pipelex's own templates. A type of its own, apart from `Jinja2TemplateRenderError`,+ # render serves Pipelex's own templates. A `SecurityError`, not a `ToolError`, in the family of+ # `UriReadRefusedError`, `SsrfBlockedError` and `UnsafeSchemaError`, so that a host catching that family+ # never absorbs it into a domain answer and never retries it. A type of its own, apart from `Jinja2TemplateRenderError`,# so that the classification of render-time template failures can tell a refusal from the rest,# although for now both are classified alike: runtime domain, message not caller-facing.passdiff --git a/pipelex/tools/jinja2/jinja2_sandbox.py b/pipelex/tools/jinja2/jinja2_sandbox.pyindex 4008047e0..8485039ca 100644--- a/pipelex/tools/jinja2/jinja2_sandbox.py+++ b/pipelex/tools/jinja2/jinja2_sandbox.py@@ -23,8 +23,9 @@ forge content, such as an image pointing at another organisation's storage key.pydantic methods, `Stuff` and content methods, classes, free functions and class methods, everymethod that changes a list, a dict or a set in place, and the few that produce bytes.- **Refusing.** A refusal raises `jinja2.exceptions.SecurityError` at the point of access, which the- render functions turn into `Jinja2TemplateSecurityError`. Jinja's stock sandbox returns an undefined- value that prints as nothing, which would send a prompt with a hole in it.+ render functions turn into `Jinja2TemplateSecurityError`, a Pipelex `SecurityError` like the runtime's+ other policy refusals. Jinja's stock sandbox returns an undefined value that prints as nothing, which+ would send a prompt with a hole in it.- **Spending.** What a template may reach says nothing about what it may spend, so every render alsospends from one budget (`jinja2_render_budget.py`), charged by the hooks of this class, by wrappersaround every filter and test, and by a rewrite of the parsed template for what no hook reachesdiff --git a/tests/unit/pipelex/tools/test_jinja2_sandbox.py b/tests/unit/pipelex/tools/test_jinja2_sandbox.pyindex 8a232be38..82377c229 100644--- a/tests/unit/pipelex/tools/test_jinja2_sandbox.py+++ b/tests/unit/pipelex/tools/test_jinja2_sandbox.py@@ -10,6 +10,7 @@ from typing import Anyimport pytest+from pipelex.base_exceptions import SecurityErrorfrom pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.stuffs.composite_content import CompositeContent@@ -19,6 +20,7 @@ from pipelex.core.stuffs.stuff import Stufffrom pipelex.core.stuffs.stuff_artefact import StuffArtefactfrom pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.core.stuffs.text_content import TextContent+from pipelex.system.exceptions import ToolErrorfrom pipelex.tools.jinja2.exceptions import Jinja2TemplateRenderError, Jinja2TemplateSecurityErrorfrom pipelex.tools.jinja2.image_registry import ImageRegistryfrom pipelex.tools.jinja2.jinja2_models import Jinja2ContextKey@@ -256,6 +258,21 @@ class TestTemplateSandbox:templating_context=_make_context(),)+ def test_refusal_is_a_security_error(self) -> None:+ """A refusal is a `SecurityError` like the runtime's other policy refusals, and never a render failure."""+ assert issubclass(Jinja2TemplateSecurityError, SecurityError)+ assert not issubclass(Jinja2TemplateSecurityError, ToolError)+ assert not issubclass(Jinja2TemplateSecurityError, Jinja2TemplateRenderError)+ assert not issubclass(Jinja2TemplateRenderError, SecurityError)+ with pytest.raises(SecurityError) as exc_info:+ render_jinja2_sync(+ template_source="{{ photos[0].model_copy() }}",+ template_category=TemplateCategory.BASIC,+ templating_context=_make_context(),+ )+ assert type(exc_info.value) is Jinja2TemplateSecurityError+ assert exc_info.value.to_error_report().error_type == "Jinja2TemplateSecurityError"+def test_sync_render_reads_metadata(self) -> None:rendered = render_jinja2_sync(template_source="{{ note._stuff_name }}: {{ note.text }}",