fred-sdk 3.3.2__tar.gz → 3.3.4__tar.gz

{fred_sdk-3.3.2 → fred_sdk-3.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fred-sdk
-Version: 3.3.2
+Version: 3.3.4
 Summary: Authoring SDK for Fred agents — graph, ReAct, and team agent primitives.
 Author-email: Thales <noreply@thalesgroup.com>
 License: Apache-2.0
@@ -12,11 +12,11 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Operating System :: OS Independent
 Requires-Python: <3.13,>=3.12
 Description-Content-Type: text/markdown
-Requires-Dist: fred-core>=3.4.2
+Requires-Dist: fred-core>=3.4.1
 Requires-Dist: pydantic<3.0.0,>=2.7.0
 Requires-Dist: langchain-core>=0.3.0
-Requires-Dist: langchain>=0.3.0
-Requires-Dist: langgraph>=1.1.3
+Requires-Dist: langchain>=1.3.14
+Requires-Dist: langgraph>=1.2.9
 Requires-Dist: httpx>=0.28.1
 Provides-Extra: dev
 Requires-Dist: bandit>=1.8.6; extra == "dev"
@@ -242,7 +242,6 @@ Built-in MCP server constants:
 | `MCP_SERVER_KNOWLEDGE_FLOW_CORPUS`         | Document search and retrieval |
 | `MCP_SERVER_KNOWLEDGE_FLOW_FS`             | Workspace file system         |
 | `MCP_SERVER_KNOWLEDGE_FLOW_TABULAR`        | Tabular data / CSV            |
-| `MCP_SERVER_KNOWLEDGE_FLOW_STATISTICS`     | Statistical analysis          |
 | `MCP_SERVER_KNOWLEDGE_FLOW_OPENSEARCH_OPS` | OpenSearch operations         |
 
 ---
@@ -264,7 +263,6 @@ class MyAgent(ReActAgent):
 | `TOOL_REF_RESOURCES_FETCH_TEXT`          | Fetch document content as text                |
 | `TOOL_REF_ARTIFACTS_PUBLISH_TEXT`        | Publish a text artifact to the workspace      |
 | `TOOL_REF_GEO_RENDER_POINTS`             | Render geographic points on a map             |
-| `TOOL_REF_LOGS_QUERY`                    | Query audit logs                              |
 | `TOOL_REF_TRACES_SUMMARIZE_CONVERSATION` | Summarize conversation traces                 |
 
 ---

{fred_sdk-3.3.2 → fred_sdk-3.3.4}/README.md

@@ -213,7 +213,6 @@ Built-in MCP server constants:
 | `MCP_SERVER_KNOWLEDGE_FLOW_CORPUS`         | Document search and retrieval |
 | `MCP_SERVER_KNOWLEDGE_FLOW_FS`             | Workspace file system         |
 | `MCP_SERVER_KNOWLEDGE_FLOW_TABULAR`        | Tabular data / CSV            |
-| `MCP_SERVER_KNOWLEDGE_FLOW_STATISTICS`     | Statistical analysis          |
 | `MCP_SERVER_KNOWLEDGE_FLOW_OPENSEARCH_OPS` | OpenSearch operations         |
 
 ---
@@ -235,7 +234,6 @@ class MyAgent(ReActAgent):
 | `TOOL_REF_RESOURCES_FETCH_TEXT`          | Fetch document content as text                |
 | `TOOL_REF_ARTIFACTS_PUBLISH_TEXT`        | Publish a text artifact to the workspace      |
 | `TOOL_REF_GEO_RENDER_POINTS`             | Render geographic points on a map             |
-| `TOOL_REF_LOGS_QUERY`                    | Query audit logs                              |
 | `TOOL_REF_TRACES_SUMMARIZE_CONVERSATION` | Summarize conversation traces                 |
 
 ---

{fred_sdk-3.3.2 → fred_sdk-3.3.4}/fred_sdk/__init__.py

@@ -34,6 +34,10 @@ Human-in-the-loop
 -----------------
     from fred_sdk import HumanInputRequest, HumanChoiceOption
 
+Capabilities (modular agent features)
+-------------------------------------
+    from fred_sdk import AgentCapability, CapabilityManifest, CapabilityContext
+
 MCP server references
 ---------------------
     from fred_sdk import MCPServerRef, MCP_SERVER_KNOWLEDGE_FLOW_CORPUS
@@ -69,11 +73,26 @@ from fred_sdk.authoring.knowledge_flow_mcp import (
     MCP_SERVER_KNOWLEDGE_FLOW_FS,
     MCP_SERVER_KNOWLEDGE_FLOW_OPENSEARCH_OPS,
     MCP_SERVER_KNOWLEDGE_FLOW_PROMETHEUS_OPS,
-    MCP_SERVER_KNOWLEDGE_FLOW_STATISTICS,
     MCP_SERVER_KNOWLEDGE_FLOW_TABULAR,
     MCP_SERVER_KNOWLEDGE_FLOW_TEXT,
     MCPServerRef,
 )
+from fred_sdk.contracts.capability import (
+    AgentCapability,
+    AssetSlot,
+    CapabilityContext,
+    CapabilityIdentity,
+    CapabilityManifest,
+    ChatControlSpec,
+    EmptyModel,
+    HitlGateRequest,
+    HitlSpec,
+    SaveContext,
+    SidePanelSpec,
+    TeamScopePolicy,
+    UploadedFile,
+    chat_part_kind,
+)
 from fred_sdk.contracts.context import (
     AgentInvocationResult,
     FsEntry,
@@ -160,7 +179,6 @@ from fred_sdk.support.builtins import (
     TOOL_REF_ARTIFACTS_PUBLISH_TEXT,
     TOOL_REF_GEO_RENDER_POINTS,
     TOOL_REF_KNOWLEDGE_SEARCH,
-    TOOL_REF_LOGS_QUERY,
     TOOL_REF_RESOURCES_FETCH_TEXT,
     TOOL_REF_TRACES_SUMMARIZE_CONVERSATION,
 )
@@ -186,7 +204,6 @@ __all__ = [
     "MCP_SERVER_KNOWLEDGE_FLOW_FS",
     "MCP_SERVER_KNOWLEDGE_FLOW_OPENSEARCH_OPS",
     "MCP_SERVER_KNOWLEDGE_FLOW_PROMETHEUS_OPS",
-    "MCP_SERVER_KNOWLEDGE_FLOW_STATISTICS",
     "MCP_SERVER_KNOWLEDGE_FLOW_TABULAR",
     "MCP_SERVER_KNOWLEDGE_FLOW_TEXT",
     # Graph authoring
@@ -236,6 +253,21 @@ __all__ = [
     "ToolRefRequirement",
     "TuningScalar",
     "TuningValue",
+    # Capability authoring (#1973, RFC AGENT-CAPABILITY-RFC.md §3)
+    "AgentCapability",
+    "AssetSlot",
+    "CapabilityContext",
+    "CapabilityIdentity",
+    "CapabilityManifest",
+    "ChatControlSpec",
+    "EmptyModel",
+    "HitlGateRequest",
+    "HitlSpec",
+    "SaveContext",
+    "SidePanelSpec",
+    "TeamScopePolicy",
+    "UploadedFile",
+    "chat_part_kind",
     # Evaluation contracts (POST /agents/evaluate)
     "EvalStep",
     "EvalTrace",
@@ -249,7 +281,6 @@ __all__ = [
     "TOOL_REF_ARTIFACTS_PUBLISH_TEXT",
     "TOOL_REF_GEO_RENDER_POINTS",
     "TOOL_REF_KNOWLEDGE_SEARCH",
-    "TOOL_REF_LOGS_QUERY",
     "TOOL_REF_RESOURCES_FETCH_TEXT",
     "TOOL_REF_TRACES_SUMMARIZE_CONVERSATION",
 ]

{fred_sdk-3.3.2 → fred_sdk-3.3.4}/fred_sdk/authoring/__init__.py

@@ -58,7 +58,6 @@ from .knowledge_flow_mcp import (
     MCP_SERVER_KNOWLEDGE_FLOW_CORPUS,
     MCP_SERVER_KNOWLEDGE_FLOW_FS,
     MCP_SERVER_KNOWLEDGE_FLOW_OPENSEARCH_OPS,
-    MCP_SERVER_KNOWLEDGE_FLOW_STATISTICS,
     MCP_SERVER_KNOWLEDGE_FLOW_TABULAR,
     MCPServerRef,
 )
@@ -69,7 +68,6 @@ __all__ = [
     "MCP_SERVER_KNOWLEDGE_FLOW_CORPUS",
     "MCP_SERVER_KNOWLEDGE_FLOW_FS",
     "MCP_SERVER_KNOWLEDGE_FLOW_OPENSEARCH_OPS",
-    "MCP_SERVER_KNOWLEDGE_FLOW_STATISTICS",
     "MCP_SERVER_KNOWLEDGE_FLOW_TABULAR",
     "ReActAgent",
     "ToolContext",

{fred_sdk-3.3.2 → fred_sdk-3.3.4}/fred_sdk/authoring/knowledge_flow_mcp.py

@@ -40,7 +40,6 @@ Current official Knowledge Flow MCP servers:
 - `MCP_SERVER_KNOWLEDGE_FLOW_CORPUS`: corpus administration operations
 - `MCP_SERVER_KNOWLEDGE_FLOW_OPENSEARCH_OPS`: OpenSearch monitoring operations
 - `MCP_SERVER_KNOWLEDGE_FLOW_TABULAR`: tabular analysis operations
-- `MCP_SERVER_KNOWLEDGE_FLOW_STATISTICS`: statistics analysis operations
 """
 
 from __future__ import annotations
@@ -63,9 +62,6 @@ MCP_SERVER_KNOWLEDGE_FLOW_OPENSEARCH_OPS: Final[str] = (
 MCP_SERVER_KNOWLEDGE_FLOW_TABULAR: Final[str] = "mcp-knowledge-flow-mcp-tabular"
 """Tabular analysis MCP server id used by Tabular-style agents."""
 
-MCP_SERVER_KNOWLEDGE_FLOW_STATISTICS: Final[str] = "mcp-knowledge-flow-statistics"
-"""Statistics analysis MCP server id used by Statistics-style agents."""
-
 MCP_SERVER_KNOWLEDGE_FLOW_TEXT: Final[str] = "mcp-knowledge-flow-mcp-text"
 """Text search MCP server id — document full-text retrieval from the knowledge flow."""
 
@@ -80,7 +76,6 @@ __all__ = [
     "MCP_SERVER_KNOWLEDGE_FLOW_FS",
     "MCP_SERVER_KNOWLEDGE_FLOW_OPENSEARCH_OPS",
     "MCP_SERVER_KNOWLEDGE_FLOW_PROMETHEUS_OPS",
-    "MCP_SERVER_KNOWLEDGE_FLOW_STATISTICS",
     "MCP_SERVER_KNOWLEDGE_FLOW_TABULAR",
     "MCP_SERVER_KNOWLEDGE_FLOW_TEXT",
 ]

{fred_sdk-3.3.2 → fred_sdk-3.3.4}/fred_sdk/contracts/__init__.py

@@ -23,6 +23,22 @@ How to use:
 - keep SDK-specific runtime code outside this package
 """
 
+from .capability import (
+    AgentCapability,
+    AssetSlot,
+    CapabilityContext,
+    CapabilityIdentity,
+    CapabilityManifest,
+    ChatControlSpec,
+    EmptyModel,
+    HitlGateRequest,
+    HitlSpec,
+    SaveContext,
+    SidePanelSpec,
+    TeamScopePolicy,
+    UploadedFile,
+    chat_part_kind,
+)
 from .context import (
     ConversationalState,
     ConversationTurn,
@@ -52,8 +68,28 @@ from .prompt_utils import (
     validate_prompt_template,
 )
 from .runtime import RuntimeErrorEvent, TurnPersistedEvent
+from .ui_part_union import (
+    BASE_UI_PARTS,
+    current_ui_part_union,
+    rebuild_ui_part_union,
+)
 
 __all__ = [
+    # Capability contracts (#1973, RFC AGENT-CAPABILITY-RFC.md §3)
+    "AgentCapability",
+    "AssetSlot",
+    "CapabilityContext",
+    "CapabilityIdentity",
+    "CapabilityManifest",
+    "ChatControlSpec",
+    "EmptyModel",
+    "HitlGateRequest",
+    "HitlSpec",
+    "SaveContext",
+    "SidePanelSpec",
+    "TeamScopePolicy",
+    "UploadedFile",
+    "chat_part_kind",
     # Conversational memory
     "ConversationTurn",
     "ConversationalState",
@@ -62,6 +98,10 @@ __all__ = [
     "LinkKind",
     "LinkPart",
     "RuntimeContext",
+    # UiPart union registration (#1977, RFC AGENT-CAPABILITY-RFC.md §3.6/§4)
+    "BASE_UI_PARTS",
+    "current_ui_part_union",
+    "rebuild_ui_part_union",
     # Execution identity and authorization (Phase 1)
     "ActorContext",
     "TeamContext",

fred_sdk-3.3.4/fred_sdk/contracts/capability/__init__.py

@@ -0,0 +1,85 @@
+# Copyright Thales 2026
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Tier 0 capability contracts (#1973, RFC docs/swift/rfc/AGENT-CAPABILITY-RFC.md §3).
+
+Why this package exists:
+- one abstraction (`AgentCapability`) carries a modular agent feature end to
+  end: declaration (`CapabilityManifest`), save-time validation, computed chat
+  surface, HITL declarations, and the runtime middleware stack
+- the runtime half (registry, boot validation, entry-point discovery, agent
+  assembly) lives in `fred_runtime.capabilities` — this package is the pure
+  contract surface capability authors import
+
+How to use:
+- `from fred_sdk.contracts.capability import AgentCapability, CapabilityManifest, ...`
+- one module per concern: `base` (the ABC), `manifest` (declaration),
+  `context` (typed runtime/LLM split), `hitl` (approval declarations)
+"""
+
+from __future__ import annotations
+
+from ..models import StoredCapabilityConfig
+from .base import AgentCapability
+from .chat_controls import (
+    ChatControlsRequest,
+    ChatControlsRequestItem,
+    ChatControlsResponse,
+    ChatControlsResult,
+)
+from .context import (
+    CapabilityContext,
+    CapabilityIdentity,
+    EmptyModel,
+    SaveContext,
+)
+from .hitl import HitlGateRequest, HitlSpec
+from .manifest import (
+    AssetSlot,
+    CapabilityCatalogEntry,
+    CapabilityManifest,
+    ChatControlDescriptor,
+    ChatControlItem,
+    ChatControlSpec,
+    SidePanelSpec,
+    TeamScopePolicy,
+    UploadedFile,
+    chat_part_kind,
+)
+
+__all__ = [
+    "AgentCapability",
+    "AssetSlot",
+    "CapabilityCatalogEntry",
+    "CapabilityContext",
+    "CapabilityIdentity",
+    "CapabilityManifest",
+    "ChatControlDescriptor",
+    "ChatControlItem",
+    "ChatControlSpec",
+    "ChatControlsRequest",
+    "ChatControlsRequestItem",
+    "ChatControlsResponse",
+    "ChatControlsResult",
+    "EmptyModel",
+    "HitlGateRequest",
+    "HitlSpec",
+    "SaveContext",
+    "SidePanelSpec",
+    "StoredCapabilityConfig",
+    "TeamScopePolicy",
+    "UploadedFile",
+    "chat_part_kind",
+]

fred_sdk-3.3.4/fred_sdk/contracts/capability/base.py

@@ -0,0 +1,180 @@
+# Copyright Thales 2026
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+`AgentCapability` — the Tier 0 abstraction for modular agent features
+(#1973, RFC AGENT-CAPABILITY-RFC.md §3.2).
+
+Why this module exists:
+- one abstraction carries a feature's declaration (manifest), its save-time
+  validation, its computed chat surface, and its runtime middleware stack —
+  replacing the per-feature scatter the RFC measures in §1.1
+
+How to use:
+- subclass with the three generic parameters and declare `manifest` plus the
+  typed models; only `middleware()` is abstract::
+
+      class PptFillerCapability(AgentCapability[PptConfig, PptStored, PptTurn]):
+          manifest = CapabilityManifest(id="ppt_filler", ...)
+          ConfigModel = PptConfig
+          StoredConfigModel = PptStored     # defaults to ConfigModel if omitted
+          TurnOptionsModel = PptTurn        # defaults to EmptyModel if omitted
+
+          def middleware(self, ctx): ...
+
+- installing the package IS the registration: declare a `fred.capabilities`
+  entry point pointing at the subclass (RFC §4, §7)
+
+Contract rules (RFC §3.2, §5.3):
+- returned middleware must act only on the capability's own tools and state
+  channels; capabilities must be mutually order-independent
+- interrupt/HITL middleware is excluded — declare `HitlSpec`s instead (§5.4)
+- capability `state_schema` channels are JSON-primitive by default; typed
+  (pydantic) channels opt into the checkpointer msgpack allowlist via
+  `manifest.state_models` (§5.2 spike rule, #1971)
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeVar, cast
+
+from pydantic import BaseModel
+
+from .context import CapabilityContext, EmptyModel, SaveContext
+from .hitl import HitlSpec
+from .manifest import CapabilityManifest, ChatControlSpec, UploadedFile
+
+if TYPE_CHECKING:
+    from langchain.agents.middleware import AgentMiddleware
+
+ConfigT = TypeVar("ConfigT", bound=BaseModel)
+StoredT = TypeVar("StoredT", bound=BaseModel)
+TurnOptionsT = TypeVar("TurnOptionsT", bound=BaseModel)
+
+
+class AgentCapability(ABC, Generic[ConfigT, StoredT, TurnOptionsT]):
+    """
+    One modular agent feature: declaration + validation + runtime middleware.
+
+    The four typed models (RFC §3.2):
+    - `ConfigModel`: what the user SENDS at agent creation (drives
+      `manifest.config_fields`)
+    - `StoredConfigModel`: what the platform PERSISTS after
+      `validate_config` enrichment; defaults to `ConfigModel`, and a
+      capability deriving state at save time declares it as a SUBCLASS of
+      `ConfigModel` (RFC §3.2)
+    - `TurnOptionsModel`: typed chat-time values (RFC §3.5); `EmptyModel`
+      if none
+    - `TeamSettingsModel`: typed per-team enablement settings (RFC §8.2);
+      `EmptyModel` until Tier 3
+    """
+
+    manifest: ClassVar[CapabilityManifest]
+    ConfigModel: ClassVar[type[BaseModel]]
+    StoredConfigModel: ClassVar[type[BaseModel]]
+    TurnOptionsModel: ClassVar[type[BaseModel]] = EmptyModel
+    TeamSettingsModel: ClassVar[type[BaseModel]] = EmptyModel
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        # StoredConfigModel defaults to ConfigModel (RFC §3.2). Only default it
+        # when the subclass declares its own ConfigModel and no
+        # StoredConfigModel is visible anywhere in the MRO.
+        if (
+            "ConfigModel" in cls.__dict__
+            and getattr(cls, "StoredConfigModel", None) is None
+        ):
+            cls.StoredConfigModel = cls.__dict__["ConfigModel"]
+
+    async def validate_config(
+        self,
+        config: ConfigT,
+        uploads: Mapping[str, list[UploadedFile]],
+        ctx: SaveContext,
+    ) -> StoredT:
+        """
+        Agent-save-time input → stored transform (RFC §3.2, §3.8).
+
+        Default: validate the input against `StoredConfigModel` unchanged —
+        correct for capabilities without save-time enrichment. Override to
+        parse uploads, raise typed validation errors, store asset binaries
+        through `ctx.services` and keep only their keys.
+        """
+
+        del uploads, ctx
+        return cast(StoredT, self.StoredConfigModel.model_validate(config.model_dump()))
+
+    def chat_controls(self, config: StoredT) -> list[ChatControlSpec]:
+        """
+        Computed chat-time control descriptors for one agent instance
+        (RFC §3.3). Evaluated at session-prep time, never persisted (§3.7).
+        List order = display order. Default: no chat controls.
+        """
+
+        del config
+        return []
+
+    def upgrade_config(self, stored: Mapping[str, Any], from_version: str) -> StoredT:
+        """
+        Migrate an old stored-config shape (RFC §3.9). Runs lazily at read
+        time. Default: plain `StoredConfigModel` validation. A raising upgrade
+        suspends the agent (`capability_config_invalid`).
+        """
+
+        del from_version
+        return cast(StoredT, self.StoredConfigModel.model_validate(stored))
+
+    def hitl_specs(self) -> Sequence[HitlSpec]:
+        """
+        Approval declarations for this capability's tools (RFC §5.4), merged
+        into the single platform HITL gate at assembly. Default: none.
+        """
+
+        return ()
+
+    @classmethod
+    def migrations_location(cls) -> str | None:
+        """
+        Filesystem path to this capability's own Alembic script directory
+        (RFC §7.1).
+
+        Why this exists:
+        - a capability that declares `manifest.tables` ships its own migration
+          scripts, applied under a per-capability version table
+          (`cap_<id>_alembic_version`) — never rebased against fred-runtime's
+          tree or another capability's (RFC §7.1)
+        - `python -m fred_runtime migrate` discovers installed capabilities via
+          the same `fred.capabilities` entry points and, for each one that
+          returns a location here, runs `alembic upgrade head` against it
+
+        How to use:
+        - return an absolute path to the package's Alembic dir (the dir holding
+          `env.py` + `versions/`), typically resolved relative to `__file__`
+        - return `None` (default) when the capability owns no tables
+        """
+
+        return None
+
+    @abstractmethod
+    def middleware(
+        self, ctx: CapabilityContext[StoredT, TurnOptionsT]
+    ) -> Sequence["AgentMiddleware"]:
+        """
+        The runtime half (RFC §3.2, §5): the LangChain middleware STACK
+        carrying this capability's tools and hooks, bound to the turn's
+        context. Authored list order is preserved within this capability's
+        block (§5.3).
+        """

fred_sdk-3.3.4/fred_sdk/contracts/capability/chat_controls.py

@@ -0,0 +1,80 @@
+# Copyright Thales 2026
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Chat-controls evaluation wire contract (#1976, RFC §3.3, §3.7).
+
+Why this module exists:
+- session prep computes each agent instance's chat-time controls on the POD
+  (capability code lives there, §7); control-plane asks the pod to evaluate
+  `chat_controls(config)` over a BATCH of capabilities in one round-trip and
+  caches the per-capability results cache-aside, keyed
+  `(capability_id, manifest.version, config_hash)` — nothing derived persisted
+- the request/response models are shared (fred-sdk) so control-plane parses the
+  pod response with the SAME model, never a hand-declared copy — same rule as
+  `CapabilityCatalogEntry`
+
+How to use:
+- control-plane: POST `ChatControlsRequest` to `/agents/capabilities/chat-controls`
+  with only the cache-MISSED capabilities; merge `ChatControlsResponse.results`
+  with cached items, then flatten into `ExecutionPreparation.chat_controls`
+- pod: evaluate each item and return one `ChatControlsResult` per capability
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from ..models import StoredCapabilityConfig
+from .manifest import ChatControlItem
+
+
+class ChatControlsRequestItem(BaseModel):
+    """One capability to evaluate: its id plus its verbatim stored slice."""
+
+    capability_id: str = Field(min_length=1)
+    # The stored envelope ({"schema_version", "config"}); None means "no stored
+    # slice" — the pod evaluates against StoredConfigModel defaults, mirroring
+    # execution-time assembly.
+    config_envelope: StoredCapabilityConfig | None = None
+
+
+class ChatControlsRequest(BaseModel):
+    """Batch chat-controls evaluation request (control-plane → pod)."""
+
+    items: list[ChatControlsRequestItem] = Field(default_factory=list)
+
+
+class ChatControlsResult(BaseModel):
+    """
+    One capability's evaluated chat controls.
+
+    `error` is non-None when the capability is not installed or its stored slice
+    could not be resolved (RFC §3.9 `capability_config_invalid`); control-plane
+    skips that capability with a warning rather than failing the whole prep.
+    `manifest_version` is the pod's installed version — the authoritative value
+    for the cache key — and is left empty on an error result (there is no
+    version to cache under, and control-plane never caches an error).
+    """
+
+    capability_id: str = Field(min_length=1)
+    manifest_version: str = ""
+    controls: list[ChatControlItem] = Field(default_factory=list)
+    error: str | None = None
+
+
+class ChatControlsResponse(BaseModel):
+    """Batch chat-controls evaluation response (pod → control-plane)."""
+
+    results: list[ChatControlsResult] = Field(default_factory=list)