fips-agents-cli 0.8.2__tar.gz → 0.10.0__tar.gz

{fips_agents_cli-0.8.2 → fips_agents_cli-0.10.0}/CLAUDE.md

@@ -6,7 +6,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **fips-agents-cli** is a Python-based CLI tool for scaffolding FIPS-compliant AI agent projects. It scaffolds MCP (Model Context Protocol) servers and AI agent projects from production-ready templates, customizes them for new projects, and prepares them for immediate development use.
 
-**Current Status:** Scaffolding commands implemented: `create mcp-server`, `create agent`, `create gateway`, `create ui`, `create sandbox`, `create model-car`. Post-scaffolding commands: `generate` (tool, resource, prompt, middleware), `patch` (check, generators, core, docs, build, all), `add` (code-executor), `vendor`. Note: `create workflow` exists in code but is not yet working.
+**Current Status:** Scaffolding commands implemented: `create mcp-server`, `create agent`, `create gateway`, `create ui`, `create sandbox`, `create model-car`. Post-scaffolding commands: `generate` (tool, resource, prompt, middleware), `patch` (check, all + type-specific category subcommands — see below), `add` (code-executor, files), `vendor`. Note: `create workflow` exists in code but is not yet working.
+
+The `patch` command is type-aware via `template.type` in `.template-info`:
+- **MCP server** projects expose `patch generators | core | docs | build`.
+- **Agent / workflow** projects expose `patch chart | docs | build | claude`.
+Running an MCP-only subcommand inside an agent project (or vice versa) exits with a clear "available categories" error. `patch check` and `patch all` work for any supported type.
 
 ## Development Commands
 

{fips_agents_cli-0.8.2 → fips_agents_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fips-agents-cli
-Version: 0.8.2
+Version: 0.10.0
 Summary: CLI tool for creating and managing FIPS-compliant AI agent projects
 Project-URL: Homepage, https://github.com/fips-agents/fips-agents-cli
 Project-URL: Repository, https://github.com/fips-agents/fips-agents-cli
@@ -23,12 +23,13 @@ Requires-Dist: click>=8.1.0
 Requires-Dist: gitpython>=3.1.0
 Requires-Dist: jinja2>=3.1.2
 Requires-Dist: rich>=13.0.0
+Requires-Dist: ruamel-yaml<0.19,>=0.18
 Requires-Dist: tomlkit>=0.12.0
 Provides-Extra: dev
-Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: black<27,>=26; extra == 'dev'
 Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
 Requires-Dist: pytest>=7.4.0; extra == 'dev'
-Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: ruff<0.12,>=0.11; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # FIPS Agents CLI
@@ -557,7 +558,9 @@ When using `--params` with `generate tool` or `generate prompt`, provide a JSON
 
 ### Patch Commands
 
-The `patch` command group updates files in existing MCP server projects from the upstream template repository without overwriting your custom code. It shows interactive diffs for files that may contain customizations.
+The `patch` command group updates files in existing projects from the upstream template repository without overwriting your custom code. It shows interactive diffs for files that may contain customizations.
+
+Supported project types: **MCP server**, **agent**, **workflow**. The available category subcommands depend on the project type — `patch` reads `template.type` from `.template-info` and surfaces a clear error if you run a category that doesn't apply (e.g. `patch generators` inside an agent project).
 
 Run these commands from within your project directory.
 
@@ -567,57 +570,68 @@ Run these commands from within your project directory.
 fips-agents patch check
 ```
 
-Check for available template updates. Shows what files have changed in the template since your project was created, organized by category.
+Check for available template updates. Shows what files have changed in the template since your project was created, organized by category. Works for any supported project type.
 
-#### `patch generators`
+#### `patch all`
 
 ```bash
-fips-agents patch generators [--dry-run]
+fips-agents patch all [--dry-run] [--skip-confirmation]
 ```
 
-Update code generator templates (Jinja2 templates in `.fips-agents-cli/generators/`).
+Update every category that applies to the current project type. Prompts for confirmation before starting unless `--skip-confirmation` is passed.
 
-#### `patch core`
+#### MCP server categories
 
-```bash
-fips-agents patch core [--dry-run]
-```
+| Subcommand           | Patches                                                                  |
+|----------------------|--------------------------------------------------------------------------|
+| `patch generators`   | Jinja2 templates in `.fips-agents-cli/generators/`                       |
+| `patch core`         | Core infrastructure (loaders, server bootstrap)                          |
+| `patch docs`         | Documentation files and examples                                         |
+| `patch build`        | Build and deployment files (Makefile, Containerfile)                     |
 
-Update core infrastructure files (loaders, server bootstrap).
+#### Agent / workflow categories
 
-#### `patch docs`
+| Subcommand     | Patches                                                                       |
+|----------------|-------------------------------------------------------------------------------|
+| `patch chart`  | Helm chart templates (`chart/templates/**`, `chart/Chart.yaml`)                |
+| `patch docs`   | `CLAUDE.md`, `AGENTS.md`, `docs/**`                                            |
+| `patch build`  | `Makefile`, `Containerfile`, `deploy.sh`, `redeploy.sh`                        |
+| `patch claude` | Claude Code slash commands shipped with the template (`.claude/commands/**`)   |
 
-```bash
-fips-agents patch docs [--dry-run]
-```
+User-customized files are never patched: for MCP this means `src/tools/`, `src/resources/`, `src/prompts/`, `src/middleware/`, `pyproject.toml`, etc. For agent/workflow it means `src/agent.py`, `agent.yaml`, `chart/values.yaml`, `src/fipsagents/**` (managed by `fips-agents vendor`), and `pyproject.toml`.
+
+All patch subcommands (except `check`) accept `--dry-run` to preview changes without modifying files.
 
-Update documentation files and examples.
+---
 
-#### `patch build`
+### Add Commands
 
-```bash
-fips-agents patch build [--dry-run]
-```
+The `add` command group wires optional capabilities into existing agent projects created with `fips-agents create agent`.
 
-Update build and deployment files (Makefile, Containerfile).
+**Run these commands from within your agent project directory.** The CLI locates the project root by looking for `.template-info` (or `agent.yaml` for legacy projects).
 
-#### `patch all`
+#### `add files`
 
 ```bash
-fips-agents patch all [--dry-run] [--skip-confirmation]
+fips-agents add files
 ```
 
-Update all patchable file categories at once. Prompts for confirmation before starting unless `--skip-confirmation` is passed.
+Enables file upload + attachment support. Flips `server.files.enabled` in `agent.yaml` and `files.enabled` in `chart/values.yaml`. The agent template already ships the rest of the files surface (storage backends, optional S3 bytes backend, ClamAV virus-scanner sidecar, Docling PDF/text extraction, pgvector chunking) — this command only wires up the toggles.
 
-All patch subcommands (except `check`) accept `--dry-run` to preview changes without modifying files.
-
----
+**What it does:**
 
-### Add Commands
+1. Sets `server.files.enabled: true` in `agent.yaml`
+2. Sets `files.enabled: true` in `chart/values.yaml`
+3. Prints next steps for installing the `[files]` extra, choosing a backend (`sqlite` / `postgres`), enabling ClamAV, and enabling persistence
 
-The `add` command group wires optional capabilities into existing agent projects created with `fips-agents create agent`.
+**Example:**
 
-**Run these commands from within your agent project directory.** The CLI locates the project root by looking for `agent.yaml`.
+```bash
+cd my-research-agent
+fips-agents add files
+pip install -e '.[files]'
+export FILES_BACKEND=sqlite
+```
 
 #### `add code-executor`
 
@@ -822,7 +836,7 @@ fips-agents-cli/
 │       ├── cli.py          # Main CLI application
 │       ├── version.py      # Version information
 │       ├── commands/       # CLI command implementations
-│       │   ├── add.py      # add code-executor (wire capabilities)
+│       │   ├── add.py      # add files / code-executor (wire capabilities)
 │       │   ├── create.py   # create mcp-server, agent, gateway, ui
 │       │   ├── generate.py # generate tool/resource/prompt/middleware
 │       │   ├── model_car.py # create model-car
@@ -946,6 +960,33 @@ MIT License - see LICENSE file for details
 
 ## Changelog
 
+### Version 0.10.0
+
+- Feature: New `tools/modality.py` helper exposing `ModalitySpec` + `apply_modality()` — declarative API for composable `add` subcommands that toggle agent.yaml / chart/values.yaml fields, drop in source files, and register pyproject.toml extras. Uses ruamel.yaml round-trip to preserve comments and `${VAR:-default}` substitutions; tomlkit for TOML edits. Idempotent, with a `precondition` hook for cross-modality dependency checks (#37)
+- Feature: New `fips-agents add files` command enables file upload + attachment support in existing agent projects. Flips `server.files.enabled` (agent.yaml) and `files.enabled` (chart/values.yaml); the agent template already ships the rest of the surface — storage backends, optional S3 bytes backend, ClamAV virus-scanner sidecar, Docling text extraction, pgvector chunking — so the command only owns the toggles (#19, #38)
+- Improvement: `add code-executor` refactored onto the new `ModalitySpec` helper. Brittle string-replace on `enabled: false` is replaced with structured ruamel.yaml round-trip; behavior preserved
+- Improvement: `_find_agent_project_root()` promoted from `commands/add.py` to `tools/project.py` as public `find_agent_project_root()`. Now recognizes both `.template-info` (`template.type=="agent"`) and legacy `agent.yaml` presence
+- Chore: Pin dev tools to `black>=26,<27` and `ruff>=0.11,<0.12` so local environments cannot silently drift past CI's formatter/linter major versions (#36)
+- Chore: New runtime dependency `ruamel.yaml>=0.18,<0.19` (used by the modality helper for comment-preserving YAML edits)
+- Chore: Descope governance issues #23 (cost tracking), #24 (HITL approval), #25 (compliance audit logging) — OGX (the new name for LlamaStack) handles these well; fips-agents-cli will not duplicate that surface
+- Tests: 29 new tests in `tests/test_modality.py` covering yaml toggles (top-level + nested), idempotency, missing-section warnings, source-file drops, pyproject extra add/merge, preconditions, and end-to-end runs of `add code-executor` and `add files`. New committed `tests/fixtures/agent_project/` provides an offline structural snapshot of the agent-template layout (precedent: `tests/fixtures/middleware_template/`)
+
+### Version 0.9.1
+
+- Chore: Realign `tests/` formatting with black 26.3.1 to match CI (v0.9.0's release pipeline failed because local black 24.x produced different output than CI's 26.x; no functional change)
+
+### Version 0.9.0
+
+- Feature: `fips-agents patch` now supports agent and workflow projects in addition to MCP servers (#12)
+- Feature: New `patch chart` and `patch claude` subcommands for agent/workflow projects (#15)
+- Feature: `.template-info` now records `template.type` and (for monorepo templates) `template.subdir` so post-scaffolding commands can route by project type (#13)
+- Feature: New `find_fips_project_root()` walks up to `.template-info`, replacing the MCP-only fastmcp-dependency probe in patch commands (#14)
+- Improvement: `_clone_template_for_patch()` resolves the monorepo subdir during patching, so glob/compare runs against `templates/agent-loop/` instead of the monorepo root (#16)
+- Improvement: Running an MCP-only subcommand inside an agent project (or vice versa) now exits with a clear "available categories" error
+- Improvement: `patch all` enumerates the project's actual category set instead of assuming MCP layout
+- Backwards compat: Projects scaffolded before `template.type` existed default to `mcp-server`; no migration required
+- Tests: 20 new tests in `tests/test_patch.py` covering the type-aware patch flow end-to-end against a fake-scaffolded agent project
+
 ### Version 0.8.2
 
 - Test: New `TestGenerateMiddlewareRealTemplate` integration test renders the real v3.x middleware Jinja2 template against each `--hook-type` and the no-flag case, with templates committed under `tests/fixtures/middleware_template/` so the suite runs offline (#3)

{fips_agents_cli-0.8.2 → fips_agents_cli-0.10.0}/README.md

@@ -524,7 +524,9 @@ When using `--params` with `generate tool` or `generate prompt`, provide a JSON
 
 ### Patch Commands
 
-The `patch` command group updates files in existing MCP server projects from the upstream template repository without overwriting your custom code. It shows interactive diffs for files that may contain customizations.
+The `patch` command group updates files in existing projects from the upstream template repository without overwriting your custom code. It shows interactive diffs for files that may contain customizations.
+
+Supported project types: **MCP server**, **agent**, **workflow**. The available category subcommands depend on the project type — `patch` reads `template.type` from `.template-info` and surfaces a clear error if you run a category that doesn't apply (e.g. `patch generators` inside an agent project).
 
 Run these commands from within your project directory.
 
@@ -534,57 +536,68 @@ Run these commands from within your project directory.
 fips-agents patch check
 ```
 
-Check for available template updates. Shows what files have changed in the template since your project was created, organized by category.
+Check for available template updates. Shows what files have changed in the template since your project was created, organized by category. Works for any supported project type.
 
-#### `patch generators`
+#### `patch all`
 
 ```bash
-fips-agents patch generators [--dry-run]
+fips-agents patch all [--dry-run] [--skip-confirmation]
 ```
 
-Update code generator templates (Jinja2 templates in `.fips-agents-cli/generators/`).
+Update every category that applies to the current project type. Prompts for confirmation before starting unless `--skip-confirmation` is passed.
 
-#### `patch core`
+#### MCP server categories
 
-```bash
-fips-agents patch core [--dry-run]
-```
+| Subcommand           | Patches                                                                  |
+|----------------------|--------------------------------------------------------------------------|
+| `patch generators`   | Jinja2 templates in `.fips-agents-cli/generators/`                       |
+| `patch core`         | Core infrastructure (loaders, server bootstrap)                          |
+| `patch docs`         | Documentation files and examples                                         |
+| `patch build`        | Build and deployment files (Makefile, Containerfile)                     |
 
-Update core infrastructure files (loaders, server bootstrap).
+#### Agent / workflow categories
 
-#### `patch docs`
+| Subcommand     | Patches                                                                       |
+|----------------|-------------------------------------------------------------------------------|
+| `patch chart`  | Helm chart templates (`chart/templates/**`, `chart/Chart.yaml`)                |
+| `patch docs`   | `CLAUDE.md`, `AGENTS.md`, `docs/**`                                            |
+| `patch build`  | `Makefile`, `Containerfile`, `deploy.sh`, `redeploy.sh`                        |
+| `patch claude` | Claude Code slash commands shipped with the template (`.claude/commands/**`)   |
 
-```bash
-fips-agents patch docs [--dry-run]
-```
+User-customized files are never patched: for MCP this means `src/tools/`, `src/resources/`, `src/prompts/`, `src/middleware/`, `pyproject.toml`, etc. For agent/workflow it means `src/agent.py`, `agent.yaml`, `chart/values.yaml`, `src/fipsagents/**` (managed by `fips-agents vendor`), and `pyproject.toml`.
+
+All patch subcommands (except `check`) accept `--dry-run` to preview changes without modifying files.
 
-Update documentation files and examples.
+---
 
-#### `patch build`
+### Add Commands
 
-```bash
-fips-agents patch build [--dry-run]
-```
+The `add` command group wires optional capabilities into existing agent projects created with `fips-agents create agent`.
 
-Update build and deployment files (Makefile, Containerfile).
+**Run these commands from within your agent project directory.** The CLI locates the project root by looking for `.template-info` (or `agent.yaml` for legacy projects).
 
-#### `patch all`
+#### `add files`
 
 ```bash
-fips-agents patch all [--dry-run] [--skip-confirmation]
+fips-agents add files
 ```
 
-Update all patchable file categories at once. Prompts for confirmation before starting unless `--skip-confirmation` is passed.
+Enables file upload + attachment support. Flips `server.files.enabled` in `agent.yaml` and `files.enabled` in `chart/values.yaml`. The agent template already ships the rest of the files surface (storage backends, optional S3 bytes backend, ClamAV virus-scanner sidecar, Docling PDF/text extraction, pgvector chunking) — this command only wires up the toggles.
 
-All patch subcommands (except `check`) accept `--dry-run` to preview changes without modifying files.
-
----
+**What it does:**
 
-### Add Commands
+1. Sets `server.files.enabled: true` in `agent.yaml`
+2. Sets `files.enabled: true` in `chart/values.yaml`
+3. Prints next steps for installing the `[files]` extra, choosing a backend (`sqlite` / `postgres`), enabling ClamAV, and enabling persistence
 
-The `add` command group wires optional capabilities into existing agent projects created with `fips-agents create agent`.
+**Example:**
 
-**Run these commands from within your agent project directory.** The CLI locates the project root by looking for `agent.yaml`.
+```bash
+cd my-research-agent
+fips-agents add files
+pip install -e '.[files]'
+export FILES_BACKEND=sqlite
+```
 
 #### `add code-executor`
 
@@ -789,7 +802,7 @@ fips-agents-cli/
 │       ├── cli.py          # Main CLI application
 │       ├── version.py      # Version information
 │       ├── commands/       # CLI command implementations
-│       │   ├── add.py      # add code-executor (wire capabilities)
+│       │   ├── add.py      # add files / code-executor (wire capabilities)
 │       │   ├── create.py   # create mcp-server, agent, gateway, ui
 │       │   ├── generate.py # generate tool/resource/prompt/middleware
 │       │   ├── model_car.py # create model-car
@@ -913,6 +926,33 @@ MIT License - see LICENSE file for details
 
 ## Changelog
 
+### Version 0.10.0
+
+- Feature: New `tools/modality.py` helper exposing `ModalitySpec` + `apply_modality()` — declarative API for composable `add` subcommands that toggle agent.yaml / chart/values.yaml fields, drop in source files, and register pyproject.toml extras. Uses ruamel.yaml round-trip to preserve comments and `${VAR:-default}` substitutions; tomlkit for TOML edits. Idempotent, with a `precondition` hook for cross-modality dependency checks (#37)
+- Feature: New `fips-agents add files` command enables file upload + attachment support in existing agent projects. Flips `server.files.enabled` (agent.yaml) and `files.enabled` (chart/values.yaml); the agent template already ships the rest of the surface — storage backends, optional S3 bytes backend, ClamAV virus-scanner sidecar, Docling text extraction, pgvector chunking — so the command only owns the toggles (#19, #38)
+- Improvement: `add code-executor` refactored onto the new `ModalitySpec` helper. Brittle string-replace on `enabled: false` is replaced with structured ruamel.yaml round-trip; behavior preserved
+- Improvement: `_find_agent_project_root()` promoted from `commands/add.py` to `tools/project.py` as public `find_agent_project_root()`. Now recognizes both `.template-info` (`template.type=="agent"`) and legacy `agent.yaml` presence
+- Chore: Pin dev tools to `black>=26,<27` and `ruff>=0.11,<0.12` so local environments cannot silently drift past CI's formatter/linter major versions (#36)
+- Chore: New runtime dependency `ruamel.yaml>=0.18,<0.19` (used by the modality helper for comment-preserving YAML edits)
+- Chore: Descope governance issues #23 (cost tracking), #24 (HITL approval), #25 (compliance audit logging) — OGX (the new name for LlamaStack) handles these well; fips-agents-cli will not duplicate that surface
+- Tests: 29 new tests in `tests/test_modality.py` covering yaml toggles (top-level + nested), idempotency, missing-section warnings, source-file drops, pyproject extra add/merge, preconditions, and end-to-end runs of `add code-executor` and `add files`. New committed `tests/fixtures/agent_project/` provides an offline structural snapshot of the agent-template layout (precedent: `tests/fixtures/middleware_template/`)
+
+### Version 0.9.1
+
+- Chore: Realign `tests/` formatting with black 26.3.1 to match CI (v0.9.0's release pipeline failed because local black 24.x produced different output than CI's 26.x; no functional change)
+
+### Version 0.9.0
+
+- Feature: `fips-agents patch` now supports agent and workflow projects in addition to MCP servers (#12)
+- Feature: New `patch chart` and `patch claude` subcommands for agent/workflow projects (#15)
+- Feature: `.template-info` now records `template.type` and (for monorepo templates) `template.subdir` so post-scaffolding commands can route by project type (#13)
+- Feature: New `find_fips_project_root()` walks up to `.template-info`, replacing the MCP-only fastmcp-dependency probe in patch commands (#14)
+- Improvement: `_clone_template_for_patch()` resolves the monorepo subdir during patching, so glob/compare runs against `templates/agent-loop/` instead of the monorepo root (#16)
+- Improvement: Running an MCP-only subcommand inside an agent project (or vice versa) now exits with a clear "available categories" error
+- Improvement: `patch all` enumerates the project's actual category set instead of assuming MCP layout
+- Backwards compat: Projects scaffolded before `template.type` existed default to `mcp-server`; no migration required
+- Tests: 20 new tests in `tests/test_patch.py` covering the type-aware patch flow end-to-end against a fake-scaffolded agent project
+
 ### Version 0.8.2
 
 - Test: New `TestGenerateMiddlewareRealTemplate` integration test renders the real v3.x middleware Jinja2 template against each `--hook-type` and the no-flag case, with templates committed under `tests/fixtures/middleware_template/` so the suite runs offline (#3)

{fips_agents_cli-0.8.2 → fips_agents_cli-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fips-agents-cli"
-version = "0.8.2"
+version = "0.10.0"
 description = "CLI tool for creating and managing FIPS-compliant AI agent projects"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -30,14 +30,18 @@ dependencies = [
     "gitpython>=3.1.0",
     "tomlkit>=0.12.0",
     "jinja2>=3.1.2",
+    "ruamel.yaml>=0.18,<0.19",
 ]
 
 [project.optional-dependencies]
 dev = [
     "pytest>=7.4.0",
     "pytest-cov>=4.1.0",
-    "black>=23.0.0",
-    "ruff>=0.1.0",
+    # Pin formatter/linter major versions so local environments cannot drift
+    # from CI silently. v0.9.0's release was broken by black 24.x vs CI's 26.x
+    # producing different output; v0.9.1 was a same-day patch to recover.
+    "black>=26,<27",
+    "ruff>=0.11,<0.12",
 ]
 
 [project.scripts]

fips_agents_cli-0.10.0/src/fips_agents_cli/commands/add.py

@@ -0,0 +1,265 @@
+"""Add command group for wiring capabilities into existing agent projects."""
+
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+
+from fips_agents_cli.tools.modality import (
+    ModalityError,
+    ModalityResult,
+    ModalitySpec,
+    SourceFile,
+    apply_modality,
+)
+from fips_agents_cli.tools.project import find_agent_project_root
+
+console = Console()
+
+
+# The code_executor tool source, embedded directly to avoid network dependencies.
+# Source: agent-template/examples/code-sandbox-agent/tools/code_executor.py
+CODE_EXECUTOR_TOOL_SOURCE = '''\
+"""Code execution tool — sends Python code to the sandbox sidecar."""
+
+import os
+
+import httpx
+
+from fipsagents.baseagent.tools import tool
+
+SANDBOX_URL = os.environ.get("SANDBOX_URL", "http://localhost:8000")
+
+
+@tool(
+    description="Execute Python code in an isolated sandbox and return the output. "
+    "Use this for any computation, math, data processing, or logic that "
+    "benefits from exact results. The code runs in a restricted environment "
+    "with access to: math, statistics, itertools, functools, re, datetime, "
+    "collections, json, csv, string, textwrap, decimal, fractions, random, "
+    "operator, typing. Use print() to produce output.",
+    visibility="llm_only",
+)
+async def code_executor(code: str, timeout: float = 10.0) -> str:
+    """Execute Python code in the sandbox sidecar.
+
+    Args:
+        code: Python source code to execute. Must use print() for output.
+        timeout: Maximum execution time in seconds (1-30).
+    """
+    timeout = max(1.0, min(timeout, 30.0))
+
+    async with httpx.AsyncClient(timeout=timeout + 5) as client:
+        try:
+            resp = await client.post(
+                f"{SANDBOX_URL}/execute",
+                json={"code": code, "timeout": timeout},
+            )
+        except httpx.ConnectError:
+            return (
+                "ERROR: Cannot connect to sandbox sidecar at "
+                f"{SANDBOX_URL}. Is it running?"
+            )
+        except httpx.TimeoutException:
+            return "ERROR: Request to sandbox timed out."
+
+    data = resp.json()
+
+    if resp.status_code == 400:
+        if "violations" in data:
+            violations = "\\n".join(f"  - {v}" for v in data["violations"])
+            return f"CODE BLOCKED by sandbox guardrails:\\n{violations}"
+        return f"ERROR: {data.get(\'error\', \'Unknown error\')}"
+
+    stdout = data.get("stdout", "").strip()
+    stderr = data.get("stderr", "").strip()
+    exit_code = data.get("exit_code", -1)
+    timed_out = data.get("timed_out", False)
+
+    if timed_out:
+        return f"TIMEOUT: Code exceeded {timeout}s limit.\\nPartial output:\\n{stdout}"
+
+    parts = []
+    if stdout:
+        parts.append(stdout)
+    if stderr:
+        parts.append(f"STDERR:\\n{stderr}")
+    if exit_code != 0:
+        parts.append(f"(exit code {exit_code})")
+
+    return "\\n".join(parts) if parts else "(no output — did you forget print()?)"
+'''
+
+
+CODE_EXECUTOR_NEXT_STEPS = (
+    "1. Build or deploy the sandbox sidecar:",
+    "   [dim]fips-agents create sandbox my-sandbox[/dim]",
+    "   or use the pre-built image from fips-agents/code-sandbox",
+    "",
+    "2. Configure the sandbox URL for your agent:",
+    "",
+    "   [bold]Sidecar mode[/bold] (same pod, default):",
+    "     The tool defaults to http://localhost:8000",
+    "     No extra config needed if sandbox runs as a sidecar container.",
+    "",
+    "   [bold]Remote service mode[/bold] (separate deployment):",
+    "     Set the SANDBOX_URL environment variable:",
+    "     [dim]export SANDBOX_URL=http://sandbox-service:8000[/dim]",
+    "",
+    "3. The agent will auto-discover tools/code_executor.py.",
+    "   Use it in your agent's step() by calling:",
+    '     [dim]await self.use_tool("code_executor", code="print(1+1)")[/dim]',
+)
+
+
+CODE_EXECUTOR_SPEC = ModalitySpec(
+    name="code-executor",
+    description="Sandbox code execution",
+    chart_values_enable="sandbox.enabled",
+    source_files=(
+        SourceFile(
+            relative_path="tools/code_executor.py",
+            content=CODE_EXECUTOR_TOOL_SOURCE,
+        ),
+    ),
+    next_steps=CODE_EXECUTOR_NEXT_STEPS,
+)
+
+
+FILES_NEXT_STEPS = (
+    r"1. Install the \[files] extra (pulls in docling + python-magic):",
+    r"   [dim]pip install -e '.\[files]'[/dim]",
+    "",
+    "2. Choose a persistence backend by setting FILES_BACKEND:",
+    "   [bold]sqlite[/bold] (dev / single-replica)",
+    "     [dim]export FILES_BACKEND=sqlite[/dim]",
+    "   [bold]postgres[/bold] (production / multi-replica)",
+    "     [dim]export FILES_BACKEND=postgres[/dim]",
+    "     [dim]export DATABASE_URL=postgresql://...[/dim]",
+    "",
+    "3. (Optional) For multi-replica deployments use the S3 bytes backend:",
+    "   [dim]chart/values.yaml: files.bytesBackend.type=s3 + bucket/region/credentials[/dim]",
+    "",
+    "4. (Optional) Enable the ClamAV virus-scanner sidecar:",
+    "   [dim]chart/values.yaml: files.virusScanner.enabled=true[/dim]",
+    "",
+    "5. (Optional) Persist uploaded bytes across pod restarts (PVC):",
+    "   [dim]chart/values.yaml: files.persistence.enabled=true[/dim]",
+    "",
+    "6. Upload a file and reference it in chat completions:",
+    "   [dim]curl -F file=@doc.pdf $AGENT_URL/v1/files[/dim]",
+    "   The response carries a file_id; pass it on subsequent",
+    "   /v1/chat/completions requests via the file_ids field.",
+)
+
+
+FILES_SPEC = ModalitySpec(
+    name="files",
+    description="File upload and attachment support",
+    agent_yaml_enable="server.files.enabled",
+    chart_values_enable="files.enabled",
+    next_steps=FILES_NEXT_STEPS,
+)
+
+
+def _print_modality_result(spec: ModalitySpec, result: ModalityResult) -> None:
+    """Render the per-action lines + the success panel for an applied spec."""
+    for action in result.actions:
+        console.print(f"[green]+[/green] {action}")
+    for skipped in result.skipped:
+        console.print(f"[dim]{skipped}[/dim]")
+    for warning in result.warnings:
+        console.print(f"[yellow]Warning:[/yellow] {warning}")
+
+    body_lines = [f"[bold green]{spec.description} added.[/bold green]", ""]
+    if spec.next_steps:
+        body_lines.append("[bold cyan]Next Steps:[/bold cyan]")
+        body_lines.append("")
+        body_lines.extend(f"  {line}" for line in spec.next_steps)
+
+    console.print(
+        Panel(
+            "\n".join(body_lines),
+            border_style="green",
+            padding=(1, 2),
+        )
+    )
+
+
+def _resolve_agent_project_or_exit() -> Path:
+    project_root = find_agent_project_root()
+    if project_root is None:
+        console.print(
+            "[red]Error:[/red] Not in an agent project directory.\n"
+            "Could not find agent.yaml or .template-info in this directory or any parent.\n\n"
+            "[yellow]Hint:[/yellow] Run this command from an agent project "
+            "created with [dim]fips-agents create agent[/dim]."
+        )
+        sys.exit(1)
+    return project_root
+
+
+@click.group()
+def add():
+    """Add capabilities to an existing agent project."""
+    pass
+
+
+def _run_modality(spec: ModalitySpec) -> None:
+    """Shared implementation for every `add <modality>` subcommand."""
+    try:
+        project_root = _resolve_agent_project_or_exit()
+        console.print(f"[green]Found project root:[/green] {project_root}")
+
+        try:
+            result = apply_modality(project_root, spec)
+        except ModalityError as e:
+            console.print(f"\n[red]Error:[/red] {e}")
+            sys.exit(1)
+
+        _print_modality_result(spec, result)
+
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Operation cancelled.[/yellow]")
+        sys.exit(130)
+    except Exception as e:
+        console.print(f"\n[red]Error:[/red] {e}")
+        sys.exit(1)
+
+
+@add.command("code-executor")
+def code_executor_cmd():
+    """Wire sandbox code execution into the current agent project.
+
+    Adds the code_executor tool to tools/ and enables the sandbox sidecar
+    in chart/values.yaml. Run from your agent project root directory.
+
+    Example:
+
+        cd my-research-agent
+
+        fips-agents add code-executor
+    """
+    _run_modality(CODE_EXECUTOR_SPEC)
+
+
+@add.command("files")
+def files_cmd():
+    """Enable file upload + attachment support in the current agent project.
+
+    Flips ``server.files.enabled`` in agent.yaml and ``files.enabled`` in
+    chart/values.yaml. The agent template already ships the rest of the
+    files surface (storage backends, S3, ClamAV sidecar, Docling parsing,
+    pgvector chunking) — this command only wires up the toggles. Follow
+    the printed next-steps to install the ``[files]`` extra and choose a
+    persistence backend.
+
+    Example:
+
+        cd my-research-agent
+
+        fips-agents add files
+    """
+    _run_modality(FILES_SPEC)