loom-kernel 2.14.0__tar.gz → 2.15.0__tar.gz

{loom_kernel-2.14.0 → loom_kernel-2.15.0}/CHANGELOG.md

@@ -137,6 +137,45 @@
   library produced the answer, the hook payload, `/agents/{name}/run`, the
   SSE `final` frame and the A2A output artifact all carry it as plain JSON
   builtins, built from the plan's `LoomType`.
+- **ai:** `ai.prices` declares model prices in USD per million tokens
+  (`input`, `output`, optional `cache_read`/`cache_write`, `source`,
+  `as_of`), keyed by the vendor model id (`loom.ai.ModelPrice`). The
+  compiler carries the bound model's price on the plan (`AgentPlan.price`)
+  and the pydantic-ai engine prices every response with it before
+  genai-prices, so `AgentUsage.cost`, `policies.max_usd` and
+  `on_unpriced_spend: refuse` work for a model the catalogue does not know
+  (a Bedrock inference profile such as `eu.anthropic.claude-haiku-5-5`):
+  `refuse` no longer fails after paying, and `serve` enforces the cap. The
+  start-up notice is skipped for a priced model. Engines may expose a
+  `prices_model(target)` oracle, read with
+  `loom.ai.registry.engine_prices_model`.
+- **ai:** `loom.ai.build_agent_runtime(config, *, root, names=None, ...)`
+  assembles an unentered `AgentRuntime` from an `ai:` section: engine,
+  artifacts under `root`, compilation. `create_app` now builds its runtime
+  through it. `AgentRuntime.plans` exposes the compiled plans.
+- **ai:** `AgentPlan.fingerprint`, a stable sha256 of what decides an
+  agent's answers: compiled instructions, output schema, output check (by
+  import path), policies, `spec_version`, the kind and name of every
+  capability and the bound provider, model, `output_mode` and `options`; not
+  the name, metadata, price, where a capability is served from, region,
+  endpoint, credentials or `streaming`.
+- **ai:** `loom.ai.etl.PolarsAgentRunner` runs an agent over a Polars frame
+  for ETL steps (see `etl`): a runtime of its own per call that also sees the
+  caller's context variables, concurrency that waits instead of refusing, one
+  output row per input row with errors as rows (an unexpected exception is an
+  `UNEXPECTED_ERROR` row, never an aborted batch, and an answer value its
+  column cannot hold an `OUTPUT_UNREPRESENTABLE` row that keeps its cost),
+  answer columns typed by the declared output (`date` as `Date`, `datetime`
+  as UTC `Datetime`, `Decimal` as `Decimal(38, 9)`, string choices as
+  `String`, ...) even for a batch
+  without rows or with errors only, tokens, cost and version per row, and a
+  budget per call that reserves `policies.max_usd` per run and is exceeded
+  only by the elastic excess of the last response of each run in flight (at
+  most `max_concurrent_runs` responses); a budget without `policies.max_usd`
+  raises `ValueError`. A frame without rows compiles nothing; `validate` and
+  `version` compile each agent once per runner, and each `map` recompiles it
+  and leaves that compilation for `version`, so `version` always equals the
+  `agent_version` the last `map` wrote.
 
 ### rest
 
@@ -211,6 +250,34 @@
   may quote the value. `ETLRunner`, `ETLRunner.from_config` and `ETLExecutor` take
   `config_context=`; `PolarsStepRunner` and `SparkStepRunner` take
   `with_config(mapping)` for fake values in tests.
+- **etl:** a step may map rows through an agent of the runner's `ai:`
+  section. `WithAgent("seller_reply", output=SellerReply, max_usd=None)`
+  declared as a class attribute is passed to `execute()` as an `AgentMapper`
+  whose `map(frame, keys=..., prompt=...)` returns, per input row, the keys,
+  the fields of `output` and `agent_version`, `agent_status`, `agent_error`,
+  `agent_input_tokens`, `agent_output_tokens`, `agent_cache_read_tokens`,
+  `agent_cache_write_tokens` and `agent_cost_usd`; `version` is the agent's
+  fingerprint, for the anti-join. A failed run is an error row; with
+  `max_usd`, the rows past the budget come back as `BUDGET_EXHAUSTED`
+  unsent; a step budget needs `policies.max_usd` on the artifact and room for
+  one run's `policies.max_usd`, and is overshot only by the elastic excess of
+  the last response of each run in flight (at most `max_concurrent_runs`
+  responses). `ETLRunner.from_yaml`
+  resolves `ai.specs` against `ai.root`, a path relative to the YAML's
+  directory (the directory itself when absent), so a config kept in a
+  subfolder reaches artifacts elsewhere in the repository while no glob may
+  leave that root, and loads `loom.ai.etl` by module path only when `ai:` is
+  present and the engine is Polars: `loom.etl` never imports `loom.ai`.
+  `ETLRunner.run` validates every declaration through the new
+  `AgentBatchRunner` port before any step runs, with new codes
+  `AGENT_NOT_FOUND`, `AGENT_COMPILATION_FAILED`, `AGENT_OUTPUT_MISMATCH`,
+  `AGENT_UNPRICED_BUDGET`, `AGENT_BUDGET_UNENFORCEABLE` (a step budget with
+  no `policies.max_usd`, or below it),
+  `AGENT_COLUMN_COLLISION` (an output field named like an `agent_*` column)
+  and `AGENT_UNSUPPORTED_ENGINE` (a Spark runner); the shape reuses
+  `MISSING_CONFIG_PARAMS`, `CONFIG_ALIAS_CONFLICT` and
+  `UNSUPPORTED_CONFIG_VALUE`. `ETLRunner`, `ETLRunner.from_config`,
+  `ETLCompiler` and `ETLExecutor` take `agents=`. Polars only.
 
 ## ⚠ Behaviour changes
 
@@ -227,6 +294,12 @@
 
 ### ai
 
+- **ai:** `load_specs`, and so `ai.specs`, refuses a glob that leaves the
+  root it resolves against — a `..` segment, an absolute pattern or a match
+  that resolves outside the root through a symlink — with
+  `AGENT_SPECS_ESCAPE_ROOT`, before reading any artifact. A deployment whose
+  `ai.specs` climbs out of the application root with `..` must move its
+  artifacts under it. Absolute patterns already failed.
 - **ai:** `CompiledOutput.decoder` and `StateShape.decoder` are gone,
   replaced by `loom_type: LoomType` (`LoomType | None` on `StateShape`); a
   reader of either field must move to `loom_type.type` / `.decode_json()` /

{loom_kernel-2.14.0 → loom_kernel-2.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.14.0
+Version: 2.15.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
@@ -16,7 +16,7 @@ Requires-Dist: msgspec<1.0,>=0.18
 Requires-Dist: omegaconf<3.0,>=2.3
 Requires-Dist: opentelemetry-api<2.0,>=1.27
 Requires-Dist: prometheus-client>=0.20
-Requires-Dist: structlog<26.0,>=24.4
+Requires-Dist: structlog<27.0,>=24.4
 Requires-Dist: typing-extensions>=4.12
 Provides-Extra: ai-a2a
 Requires-Dist: a2a-sdk<2,>=1.1; extra == 'ai-a2a'

{loom_kernel-2.14.0 → loom_kernel-2.15.0}/pyproject.toml

@@ -15,7 +15,7 @@ classifiers = [
 ]
 dependencies = [
     "msgspec>=0.18,<1.0",
-    "structlog>=24.4,<26.0",
+    "structlog>=24.4,<27.0",
     "omegaconf>=2.3,<3.0",
     "prometheus-client>=0.20",
     "aiocache>=0.12,<1.0",

{loom_kernel-2.14.0 → loom_kernel-2.15.0}/src/loom/ai/__init__.py

@@ -43,6 +43,7 @@ from loom.ai.abc import (
     ToolsetContext,
     ToolsetFactory,
 )
+from loom.ai.bootstrap import build_agent_runtime
 from loom.ai.config import A2AConfig, AgentEndpointConfig, AiConfig
 from loom.ai.errors import (
     AgentCompilationError,
@@ -54,6 +55,7 @@ from loom.ai.errors import (
     is_retriable,
 )
 from loom.ai.inference import InferenceTarget
+from loom.ai.pricing import ModelPrice
 from loom.ai.runtime import AgentHealth, AgentRuntime
 
 __all__ = [
@@ -89,6 +91,7 @@ __all__ = [
     "McpSession",
     "McpToolCallResult",
     "McpToolInfo",
+    "ModelPrice",
     "NativeCapableEngine",
     "OutputCheck",
     "Prompt",
@@ -98,4 +101,5 @@ __all__ = [
     "ToolResultEvent",
     "ToolsetContext",
     "ToolsetFactory",
+    "build_agent_runtime",
 ]

loom_kernel-2.15.0/src/loom/ai/_paths.py

@@ -0,0 +1,33 @@
+"""Containment of relative paths inside the directory they are anchored to."""
+
+from __future__ import annotations
+
+from pathlib import Path, PurePath
+
+__all__ = ["escapes", "is_within"]
+
+
+def escapes(relative: str) -> bool:
+    """Report whether *relative* could name something outside its anchor.
+
+    Args:
+        relative: Path or glob written relative to an anchor directory.
+
+    Returns:
+        ``True`` when it is absolute or climbs with a ``..`` segment.
+    """
+    path = PurePath(relative)
+    return path.is_absolute() or ".." in path.parts
+
+
+def is_within(path: Path, root: Path) -> bool:
+    """Report whether *path*, symlinks resolved, stays inside *root*.
+
+    Args:
+        path: Path found on disk.
+        root: Directory *path* must not leave.
+
+    Returns:
+        Whether the resolved *path* is *root* or below it.
+    """
+    return path.resolve().is_relative_to(root.resolve())

loom_kernel-2.15.0/src/loom/ai/bootstrap.py

@@ -0,0 +1,120 @@
+"""Assembly of an agent runtime from a deployment's ``ai:`` section.
+
+The one path every transport takes from configuration to a live
+:class:`~loom.ai.runtime.AgentRuntime`: resolve the engine, load and compile
+the artifacts, and hand both to the runtime, which opens nothing until it is
+entered.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection, Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from loom.ai.abc import AgentEngineProvider, DepsFactory
+from loom.ai.compiler import AgentCompiler
+from loom.ai.config import AiConfig
+from loom.ai.declarative import DecodedSpec, load_specs
+from loom.ai.registry import (
+    configure_engine_mcp_connect_timeout,
+    engine_client_factories,
+    engine_native_tool_support,
+    engine_supported_kinds,
+    resolve_engine_provider,
+)
+from loom.ai.runtime import AgentRuntime, UseCaseMcpGrant
+from loom.core.di import LoomContainer
+from loom.core.identity import Identity
+from loom.core.sql.config import SqlConfig
+from loom.core.use_case.registry import UseCaseRegistry
+
+__all__ = ["build_agent_runtime"]
+
+
+class _NoDependencies(DepsFactory):
+    """Dependency factory of a runtime whose agents reach no application service."""
+
+    def build(
+        self,
+        identity: Identity,
+        container: LoomContainer,
+        state: Mapping[str, Any] | None = None,
+    ) -> object:
+        return None
+
+
+def build_agent_runtime(
+    config: AiConfig,
+    *,
+    root: Path | str,
+    names: Collection[str] | None = None,
+    specs: Sequence[str] | None = None,
+    engine_provider: AgentEngineProvider | None = None,
+    registry: UseCaseRegistry | None = None,
+    container: LoomContainer | None = None,
+    deps: DepsFactory | None = None,
+    sql: SqlConfig | None = None,
+    use_case_mcp: Sequence[UseCaseMcpGrant] = (),
+) -> AgentRuntime:
+    """Compile the declared artifacts and build the runtime that serves them.
+
+    Compilation is offline and complete: every issue of every artifact is
+    reported at once. No client opens until the returned runtime is entered.
+
+    Args:
+        config: Parsed ``ai:`` section.
+        root: Directory the artifact globs are resolved against; no glob may
+            leave it.
+        names: Agents to serve; ``None`` serves every artifact found.
+        specs: Artifact globs replacing ``config.specs``.
+        engine_provider: Engine provider to build engines with; resolved from
+            ``config.engine`` when omitted.
+        registry: Use cases ``usecase`` grants and hooks resolve against;
+            empty when omitted.
+        container: Application container engines resolve services from;
+            empty when omitted.
+        deps: Per-invocation dependency factory; when omitted every run gets
+            no dependency bundle.
+        sql: Data-layer configuration ``sql`` grants resolve against.
+        use_case_mcp: Compiled ``Mcp()`` marker grants of the application's
+            use cases.
+
+    Returns:
+        The runtime, not yet entered.
+
+    Raises:
+        AgentCompilationError: When the engine cannot be resolved, a glob
+            leaves *root*, or an artifact does not compile.
+    """
+    provider = engine_provider or resolve_engine_provider(config.engine)
+    configure_engine_mcp_connect_timeout(provider, config.startup_timeout_ms / 1000)
+    mcp_factory, a2a_factory = engine_client_factories(provider)
+    compiler = AgentCompiler(
+        config=config,
+        registry=registry or UseCaseRegistry.build([]),
+        supported_kinds=engine_supported_kinds(provider, config.engine),
+        sql=sql,
+        native_tools=engine_native_tool_support(provider),
+    )
+    decoded = load_specs(config.specs if specs is None else specs, root=root)
+    plans = compiler.compile_all(_named(decoded, names))
+    return AgentRuntime(
+        plans=plans,
+        config=config,
+        engine_provider=provider,
+        deps=deps or _NoDependencies(),
+        container=container or LoomContainer(),
+        sql_config=sql,
+        mcp_client_factory=mcp_factory,
+        a2a_client_factory=a2a_factory,
+        use_case_mcp=use_case_mcp,
+    )
+
+
+def _named(
+    decoded: Sequence[DecodedSpec], names: Collection[str] | None
+) -> tuple[DecodedSpec, ...]:
+    if names is None:
+        return tuple(decoded)
+    return tuple(item for item in decoded if item.spec.name in names)

{loom_kernel-2.14.0 → loom_kernel-2.15.0}/src/loom/ai/compiler/_compiler.py

@@ -37,6 +37,7 @@ from loom.ai.errors import (
     agent_name_duplicate,
 )
 from loom.ai.inference import InferenceTarget
+from loom.ai.pricing import ModelPrice
 from loom.core.sql.config import SqlConfig
 from loom.core.use_case.registry import UseCaseRegistry
 
@@ -176,6 +177,7 @@ class AgentCompiler:
             instructions,
             state,
             inference,
+            self._config.prices.get(inference.model),
             output,
             output_check,
             capabilities,
@@ -191,6 +193,7 @@ class AgentCompiler:
         instructions: tuple[CompiledInstruction, ...],
         state: StateShape | None,
         inference: InferenceTarget,
+        price: ModelPrice | None,
         output: CompiledOutput,
         output_check: OutputCheck | None,
         capabilities: tuple[CompiledCapability, ...],
@@ -205,6 +208,7 @@ class AgentCompiler:
             state=state,
             spec_version=spec.spec_version,
             inference=inference,
+            price=price,
             output=output,
             output_check=output_check,
             capabilities=capabilities,

loom_kernel-2.15.0/src/loom/ai/compiler/_fingerprint.py

@@ -0,0 +1,70 @@
+"""Fingerprint of the facts of a compiled plan that decide its answers."""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Final
+
+import msgspec
+
+from loom.ai.abc import OutputCheck
+
+if TYPE_CHECKING:
+    from loom.ai.compiler._plan import AgentPlan, CompiledCapability
+
+_CAPABILITY_NAMES: Final[Mapping[str, tuple[str, ...]]] = MappingProxyType(
+    {
+        "usecase": ("keys",),
+        "sql": ("connection",),
+        "mcp": ("server",),
+        "skills": ("library", "names"),
+        "python": ("factory_ref",),
+        "a2a": ("agent",),
+        "native": ("tool",),
+    }
+)
+
+
+def plan_fingerprint(plan: AgentPlan) -> str:
+    """Return the sha256 of what decides *plan*'s answers.
+
+    Args:
+        plan: Compiled plan.
+
+    Returns:
+        Hex digest over the instructions, output schema and check, policies,
+        format version, the kind and name of every capability and the model
+        binding, without the deployment details.
+    """
+    facts = {
+        "spec_version": plan.spec_version,
+        "instructions": [[block.text, block.template] for block in plan.instructions],
+        "output_schema": plan.output.schema,
+        "output_check": _reference(plan.output_check),
+        "policies": plan.policies,
+        "capabilities": [_capability(capability) for capability in plan.capabilities],
+        "provider": plan.inference.provider,
+        "model": plan.inference.model,
+        "output_mode": plan.inference.output_mode,
+        "options": plan.inference.options,
+    }
+    encoded = msgspec.json.encode(facts, order="sorted", enc_hook=_as_dict)
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def _as_dict(value: object) -> dict[object, object]:
+    if isinstance(value, Mapping):
+        return dict(value)
+    raise NotImplementedError(f"cannot fingerprint {type(value).__name__}")
+
+
+def _reference(check: OutputCheck | None) -> str | None:
+    if check is None:
+        return None
+    return f"{check.__module__}:{check.__qualname__}"
+
+
+def _capability(capability: CompiledCapability) -> list[object]:
+    return [capability.kind, *(getattr(capability, a) for a in _CAPABILITY_NAMES[capability.kind])]

{loom_kernel-2.14.0 → loom_kernel-2.15.0}/src/loom/ai/compiler/_plan.py

@@ -24,8 +24,10 @@ from typing import Any, ClassVar, Final
 import msgspec
 
 from loom.ai.abc import OutputCheck, StateShape
+from loom.ai.compiler._fingerprint import plan_fingerprint
 from loom.ai.declarative import PolicySpec
 from loom.ai.inference import InferenceTarget
+from loom.ai.pricing import ModelPrice
 from loom.core.engine.compilable import Compilable
 from loom.core.model import LoomFrozenStruct, LoomType
 from loom.core.sql.config import SqlConnectionConfig
@@ -391,6 +393,8 @@ class AgentPlan(LoomFrozenStruct, frozen=True, kw_only=True):
             artifact declares neither ``deps_type`` nor ``deps_schema``.
         spec_version: Artifact format version, retained for self-description.
         inference: Resolved model binding; one binding, no fallback (FR-019a).
+        price: Configured price of the bound model, from ``ai.prices``, or
+            ``None`` when the deployment declares none for it.
         output: Structured-output contract with its compiled boundary type.
         output_check: Resolved predicate over the answer the engine parsed,
             when the artifact declares ``output_check``; ``None`` otherwise.
@@ -402,12 +406,28 @@ class AgentPlan(LoomFrozenStruct, frozen=True, kw_only=True):
         source_path: Artifact provenance for error messages, when known.
     """
 
+    @property
+    def fingerprint(self) -> str:
+        """Stable sha256 of everything that decides this agent's answers.
+
+        Covers the instructions as compiled, the output schema, the output
+        check, the policies, the format version, the kind and name of every
+        capability and the bound provider, model, output mode and options.
+        Leaves out the name, description, metadata, provenance, configured
+        price, where a capability is served from (URL, directory,
+        credentials, timeouts) and the binding's region, endpoint,
+        credentials and streaming flag. The output check enters by its import
+        path, so editing the check's body keeps the fingerprint.
+        """
+        return plan_fingerprint(self)
+
     name: str
     description: str
     instructions: tuple[CompiledInstruction, ...]
     state: StateShape | None = None
     spec_version: int
     inference: InferenceTarget
+    price: ModelPrice | None = None
     output: CompiledOutput
     output_check: OutputCheck | None = None
     capabilities: tuple[CompiledCapability, ...] = ()

{loom_kernel-2.14.0 → loom_kernel-2.15.0}/src/loom/ai/compiler/phases/_capabilities.py

@@ -21,6 +21,7 @@ from pathlib import Path
 from typing import Any, Final
 
 from loom.ai._filters import select_names
+from loom.ai._paths import escapes, is_within
 from loom.ai.abc import NativeToolSupport
 from loom.ai.compiler._plan import (
     CompiledA2ACapability,
@@ -354,12 +355,6 @@ def _compile_a2a(capability: A2ACapability, context: _Context) -> _HandlerResult
     )
 
 
-def _library_escapes(library: str) -> bool:
-    """Report whether a library name would leave the directory it is anchored to."""
-    name = library.removeprefix(_LOCAL_LIBRARY_PREFIX)
-    return ".." in Path(name).parts
-
-
 def _library_base(library: str, context: _Context) -> _ResolveResult:
     """Return the directory ``library`` is anchored to, or why it has none."""
     if library.startswith(_LOCAL_LIBRARY_PREFIX):
@@ -373,15 +368,15 @@ def _library_base(library: str, context: _Context) -> _ResolveResult:
 
 
 def _resolve_library(library: str, context: _Context) -> _ResolveResult:
-    if _library_escapes(library):
+    if escapes(library.removeprefix(_LOCAL_LIBRARY_PREFIX)):
         return None, [skills_library_escapes(context.component, library)]
     base, issues = _library_base(library, context)
     if base is None:
         return None, issues
-    resolved = (base / library.removeprefix(_LOCAL_LIBRARY_PREFIX)).resolve()
-    if not resolved.is_relative_to(base.resolve()):
+    resolved = base / library.removeprefix(_LOCAL_LIBRARY_PREFIX)
+    if not is_within(resolved, base):
         return None, [skills_library_escapes(context.component, library)]
-    return resolved, []
+    return resolved.resolve(), []
 
 
 def _discover_skills(directory: Path) -> tuple[tuple[str, ...], str | None]:

{loom_kernel-2.14.0 → loom_kernel-2.15.0}/src/loom/ai/config.py

@@ -38,6 +38,7 @@ from loom.ai.errors import (
     remote_clients_unknown,
 )
 from loom.ai.inference import OUTPUT_MODES, InferenceTarget
+from loom.ai.pricing import ModelPrice
 from loom.ai.remote_auth import is_strategy_registered, registered_strategy_names
 from loom.core.model import LoomFrozenStruct
 
@@ -339,6 +340,10 @@ class AiConfig(LoomFrozenStruct, frozen=True, kw_only=True):
             one of the two declares the artifacts of an application, and
             declaring both is a compilation error.
         models: Model-role bindings; must contain every role an agent declares.
+        prices: Prices keyed by vendor model id (``InferenceTarget.model``).
+            A plan bound to a listed model is priced with these rates rather
+            than the engine's own, which is what keeps ``policies.max_usd``
+            enforceable for a model the engine cannot price.
         skills_root: Filesystem root bare skill library names resolve against.
         mcp_servers: Named remote MCP servers artifacts refer to by name.
         a2a_agents: Named remote A2A agents artifacts refer to by name.
@@ -390,6 +395,7 @@ class AiConfig(LoomFrozenStruct, frozen=True, kw_only=True):
     engine: str
     models: dict[str, InferenceTarget]
     specs: tuple[str, ...] = ()
+    prices: dict[str, ModelPrice] = field(default_factory=dict)
     skills_root: str | None = None
     mcp_servers: dict[str, McpServerConfig] = field(default_factory=dict)
     a2a_agents: dict[str, A2AAgentConfig] = field(default_factory=dict)

{loom_kernel-2.14.0 → loom_kernel-2.15.0}/src/loom/ai/declarative/__init__.py

@@ -18,7 +18,13 @@ from pathlib import Path
 from types import MappingProxyType
 from typing import Final, TypeVar
 
-from loom.ai.errors import AgentCompilationError, AgentCompilationIssue, spec_malformed
+from loom.ai._paths import escapes, is_within
+from loom.ai.errors import (
+    AgentCompilationError,
+    AgentCompilationIssue,
+    agent_specs_escape_root,
+    spec_malformed,
+)
 
 from ._envelope import (
     LATEST_SPEC_VERSION,
@@ -122,10 +128,24 @@ _LOADERS: Final[Mapping[str, Callable[[bytes, str], DecodedSpec]]] = MappingProx
 )
 
 
+def _glob(pattern: str, root: Path) -> tuple[set[Path], list[AgentCompilationIssue]]:
+    if escapes(pattern):
+        return set(), [agent_specs_escape_root(pattern)]
+    matches = {path for path in root.glob(pattern) if path.is_file()}
+    if not all(is_within(path, root) for path in matches):
+        return set(), [agent_specs_escape_root(pattern)]
+    return matches, []
+
+
 def _resolve_paths(patterns: Sequence[str], root: Path) -> tuple[Path, ...]:
     matches: set[Path] = set()
+    issues: list[AgentCompilationIssue] = []
     for pattern in patterns:
-        matches.update(path for path in root.glob(pattern) if path.is_file())
+        found, pattern_issues = _glob(pattern, root)
+        matches.update(found)
+        issues.extend(pattern_issues)
+    if issues:
+        raise AgentCompilationError(issues)
     return tuple(sorted(matches))
 
 
@@ -154,8 +174,11 @@ def load_specs(
 ) -> tuple[DecodedSpec, ...]:
     """Load every artifact matching a set of globs.
 
-    Patterns are resolved relative to ``root``; matches are de-duplicated across
-    patterns and returned sorted by path, so the result is deterministic.
+    Patterns are resolved relative to ``root`` and may not leave it: an
+    absolute pattern, a ``..`` segment or a match whose resolved path lies
+    outside ``root`` is refused before any artifact is read. Matches are
+    de-duplicated across patterns and returned sorted by path, so the result
+    is deterministic.
     ``.yaml``/``.yml`` files decode as YAML, ``.json`` files as JSON, and any
     other extension is a failure.
 
@@ -172,8 +195,9 @@ def load_specs(
         One decoded artifact per matched file, ordered by path.
 
     Raises:
-        AgentCompilationError: Aggregating every fatal issue found across all
-            matched files.
+        AgentCompilationError: With ``AGENT_SPECS_ESCAPE_ROOT`` for every
+            pattern that leaves ``root``; otherwise aggregating every fatal
+            issue found across all matched files.
 
     Example:
         >>> load_specs(["*.agent.yaml"], root="agents")