Phase 2 + Phase 3a/3b: session state, diagnostics, 5 new tools, docs (0.1.3 → 0.2.0)

AGENTS.md

@@ -40,11 +40,13 @@ objects (`ListToolsResult`, `CallToolResult`, `ListResourcesResult`).
 | `src/deep_agentic_core_mcp/config.py` | Server identity and shared constants |
 | `src/deep_agentic_core_mcp/tools/` | Tool implementations (`core.py`) and registry (`registry.py`) |
 | `src/deep_agentic_core_mcp/resources/` | MCP resource definitions and catalog |
-| `src/deep_agentic_core_mcp/prompts/` | Reusable prompt templates (planned) |
+| `src/deep_agentic_core_mcp/prompts/` | Reusable prompt templates, wired into `prompts/list`/`prompts/get` |
 | `src/deep_agentic_core_mcp/schemas/` | Request/response contracts |
 | `src/deep_agentic_core_mcp/services/` | Shared orchestration logic |
 | `src/deep_agentic_core_mcp/adapters/` | Integration boundaries to agenticlens and agentic-chaos |
 | `tests/` | Pytest tests (asyncio_mode=auto) |
+| `scripts/generate_tools_doc.py` | Generates `docs/tools.md` from `tools/registry.py` |
+| `docs/tools.md` | **Generated** — never hand-edit, run `make docs` |
 | `server.json` | MCP Registry metadata |
 | `Makefile` | Local dev automation |
 
@@ -56,9 +58,11 @@ objects (`ListToolsResult`, `CallToolResult`, `ListResourcesResult`).
 ## Adding a New Tool
 
 1. Add implementation in `tools/` (return a dict)
-2. Register in `tools/registry.py` (name + description)
+2. Register in `tools/registry.py` (name, description, and the metadata
+   fields: `category`, `prerequisites`, `expected_duration`, `mutates_session`)
 3. Add handler entry in `server.py` `_TOOL_DISPATCH`
 4. Add test in `tests/test_server.py`
+5. Run `make docs` to regenerate `docs/tools.md`
 
 ## Package Boundaries
 
@@ -70,6 +74,9 @@ objects (`ListToolsResult`, `CallToolResult`, `ListResourcesResult`).
 ## Pre-push Checklist
 
 Run `make check` before every push. It runs: lint → format-check → typecheck → test.
+If `tools/registry.py` changed, also run `make docs-check` (regenerates
+`docs/tools.md` and fails if that changed anything you didn't commit) —
+not part of `check` itself so the default gate stays fast.
 
 ## Release
 

CHANGELOG.md

@@ -4,6 +4,61 @@ All notable changes to this project will be documented here.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## 0.2.0 - 2026-08-08
+
+### Added
+
+- `core.verify` tool checking agenticlens, agentic-chaos, and ai-operations-spec connectivity.
+- `core.session_state` tool exposing the in-memory session's stored artifacts and call history.
+- In-memory session store (`services/session.py`) so `lens.analyze_workflow` -> `lens.report_summary`
+  -> `lens.compare_runs` -> `chaos.run_experiment` can share artifacts without the client resending
+  them; tools accept an optional `session_id` argument.
+- `lens.report_summary` tool rendering a Markdown workflow report via AgenticLens's `MarkdownExporter`.
+- `lens.compare_runs` tool wrapping AgenticLens's baseline/candidate trace comparison and regression
+  detection.
+- `lens.slo_summary` tool applying release-gate style SLO thresholds to an evaluation report.
+- `lens.audit_report` tool returning case-by-case evaluation detail, optionally with an HTML report.
+- `chaos.run_experiment` tool running a workspace-sandboxed target script inside a chaos session and
+  reporting the resulting fault events (mirrors the agentic-chaos CLI's `chaos run`).
+- `examples/chaos_target.py`, a minimal `chaos_call()`-instrumented script for `chaos.run_experiment`.
+- Real `prompts/list` and `prompts/get` handlers, with prompt arguments and rendered templates
+  (previously the prompt registry existed but was never wired into the server).
+- Tool metadata (`category`, `prerequisites`, `expected_duration`, `mutates_session`) on every tool,
+  surfaced to MCP hosts via `Tool.annotations`/`Tool._meta`.
+- `core.health` now returns adapter availability/version, loaded tool/resource/prompt counts, the
+  resolved workspace root, and recent successful-call timestamps, instead of just `{"status": "ok"}`.
+- `docs/tools.md`, a generated tool reference (name, description, category, prerequisites, expected
+  duration, mutation/side-effect flags, and full input schema per tool) produced by
+  `scripts/generate_tools_doc.py` from `tools/registry.py`, so it can't drift out of sync with what
+  `tools/list` actually returns. `make docs` regenerates it; `make docs-check` fails if it's stale.
+
+### Changed
+
+- Adapters (`adapters/agenticlens.py`, `adapters/agentic_chaos.py`, `adapters/ai_operations_spec.py`)
+  now import their sibling repo defensively: a missing/broken sibling no longer crashes server boot,
+  it surfaces as `"available": false` through `core.verify`/`core.health` and a structured tool error.
+
+### Fixed
+
+- `chaos.run_experiment`'s `timeout_seconds` now actually bounds wall-clock time. It previously ran
+  the worker thread inside a `with ThreadPoolExecutor(...)` block, whose `__exit__` calls
+  `shutdown(wait=True)` and blocked for the thread to finish regardless of the timeout having already
+  fired.
+- `server.py` no longer indexes `SCHEMA_DOCUMENTS` directly when building the schemas resources
+  (`SCHEMA_DOCUMENTS["workflow.schema.json"]`, etc.); a missing/broken `ai-operations-spec` sibling
+  used to raise `KeyError` at import time, crashing server boot before `core.verify` could report it
+  as unavailable. `ai_operations_spec.py` now exposes `schema_resource_content()`/
+  `list_schema_resources()` that both derive from what actually loaded, so `resources/list` and
+  `resources/read` degrade consistently with everything else.
+- `examples/sample_workflow.json` previously failed `Workflow` validation outright (missing
+  `start_time`) and was too thin to exercise the recommendation engine even if fixed. It's now a
+  valid, richer workflow (6 steps, real metrics) that produces real `lens.analyze_workflow`/
+  `lens.report_summary` recommendations (excessive retrieved chunks, a duplicate tool call, long
+  conversation history) instead of an empty or erroring result.
+- `handle_call_tool` now catches any exception a tool handler raises (e.g. a pydantic
+  `ValidationError` from malformed workflow/run input) and returns a structured
+  `{"ok": false, "error": ...}` payload instead of letting it propagate past the MCP dispatch boundary.
+
 ## 0.1.3 - 2026-08-07
 
 ### Added

Makefile

@@ -1,6 +1,6 @@
 .DEFAULT_GOAL := help
 
-.PHONY: help install lint format format-check typecheck test test-cov clean build check
+.PHONY: help install lint format format-check typecheck test test-cov clean build check docs docs-check
 
 help: ## Show this help
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | \
@@ -33,4 +33,10 @@ clean: ## Remove build artifacts
 build: ## Build package distributions
 	uv run python -m build
 
+docs: ## Regenerate generated docs (docs/tools.md) from tools/registry.py
+	uv run python scripts/generate_tools_doc.py
+
+docs-check: docs ## Fail if docs/tools.md is out of date (regenerates, then diffs)
+	git diff --exit-code docs/tools.md
+
 check: lint format-check typecheck test ## Run all quality gates

README.md

@@ -45,35 +45,41 @@ Planned capability areas:
 - Python-first: package and publish through PyPI
 - Thin orchestration layer: reuse `agenticlens` and `agentic-chaos` instead of
   re-implementing their logic
-- Local-first: work well as a stdio MCP server for developer workflows
+- Local-first: work well as a stdio MCP server for developer workflows —
+  this matters because `chaos.run_experiment` executes real code (see
+  [SECURITY.md](SECURITY.md)), so this server is meant for trusted,
+  local/stdio use, not exposure to untrusted clients
 - Expandable: leave room for a later remote deployment mode if needed
 
-## Initial Scope
-
-The first milestone is foundation only:
-
-- repository structure
-- packaging metadata
-- MCP registry metadata
-- roadmap and product framing
-- minimal server entrypoint and tool layout
-
-The first working implementation can stay intentionally small while the shape of
-the tool surface stabilizes.
-
-## Proposed MCP Surface
-
-Possible first tool groups:
-
-- `lens.profile_workflow`
-- `lens.analyze_workflow`
-- `chaos.run_experiment`
-- `chaos.list_faults`
-- `core.health`
-- `core.version`
-
-These names are placeholders, but the structure matters: one server can expose
-multiple tools without needing multiple MCP packages or registry entries.
+## MCP Surface (current, `0.2.0`)
+
+- `core.health` — rich diagnostics: adapter availability/version, loaded
+  tool/resource/prompt counts, workspace root, recent successful calls
+- `core.version` — server package version
+- `core.verify` — checks agenticlens/agentic-chaos/ai-operations-spec
+  connectivity and reports readiness
+- `core.session_state` — inspect what the active session has accumulated
+- `lens.analyze_workflow` — run AgenticLens recommendations against a
+  workflow artifact
+- `lens.report_summary` — render a Markdown workflow report
+- `lens.compare_runs` — compare baseline/candidate trace runs for
+  regressions
+- `lens.slo_summary` — apply release-gate style SLO thresholds to an
+  evaluation report
+- `lens.audit_report` — case-by-case evaluation detail, optionally with HTML
+- `chaos.list_faults` — list the supported fault types
+- `chaos.run_experiment` — run a workspace-sandboxed target script under
+  selected faults ([executes real code — see `SECURITY.md`](SECURITY.md))
+- `spec.validate_artifact` — validate a workflow/run artifact against the AI
+  Operations v0.4 draft
+
+Sequential tool calls can share context via an optional `session_id`
+argument, backed by an in-memory session store — see `ROADMAP.md` Phase 2.
+
+See [ROADMAP.md](ROADMAP.md) for what's shipped per phase and what's still
+open, and [docs/tools.md](docs/tools.md) for full input schemas and
+per-tool metadata (generated from `tools/registry.py`, run `make docs` to
+refresh it after changing that file).
 
 ## Repository Layout
 
@@ -85,9 +91,13 @@ mcp-server/
 ├── server.json
 ├── .gitignore
 ├── docs/
-│   └── architecture.md
+│   ├── architecture.md
+│   └── tools.md          # generated - see scripts/generate_tools_doc.py
 ├── examples/
-│   └── sample_workflow.json
+│   ├── sample_workflow.json
+│   └── chaos_target.py
+├── scripts/
+│   └── generate_tools_doc.py
 ├── src/
 │   └── deep_agentic_core_mcp/
 │       ├── __init__.py
@@ -104,20 +114,26 @@ mcp-server/
 │       │   └── tooling.py
 │       ├── services/
 │       │   ├── __init__.py
-│       │   └── registry.py
+│       │   ├── registry.py
+│       │   └── session.py
 │       ├── adapters/
 │       │   ├── __init__.py
 │       │   ├── agentic_chaos.py
-│       │   └── agenticlens.py
+│       │   ├── agenticlens.py
+│       │   └── ai_operations_spec.py
 │       └── tools/
 │           ├── __init__.py
 │           ├── registry.py
 │           ├── chaos.py
 │           ├── core.py
-│           └── lens.py
+│           ├── lens.py
+│           └── spec.py
 └── tests/
+    ├── test_degraded_boot.py
     ├── test_imports.py
-    └── test_registry.py
+    ├── test_registry.py
+    ├── test_server.py
+    └── test_session.py
 ```
 
 ## MCP-Oriented Structure
@@ -130,12 +146,11 @@ MCP server:
   workflow examples
 - `prompts/` for reusable prompt templates exposed through the server
 - `schemas/` for typed request and response contracts
-- `services/` for shared orchestration logic that keeps tool modules thin
-- `adapters/` for integration boundaries to `agenticlens` and
-  `agentic-chaos`
-
-The implementation is still early, but the file structure now reflects that
-shape so we can add functionality without reshuffling the repo later.
+- `services/` for shared orchestration logic that keeps tool modules thin,
+  including the in-memory session store (`services/session.py`)
+- `adapters/` for integration boundaries to `agenticlens`, `agentic-chaos`,
+  and `ai-operations-spec` — each degrades to `"available": false` rather
+  than crashing server boot if its sibling repo is missing
 
 ## Packaging and Publishing Model
 
@@ -147,28 +162,21 @@ shape so we can add functionality without reshuffling the repo later.
 For PyPI-based verification, the `mcp-name` marker above must match the
 `name` field in `server.json`.
 
-## Near-Term Build Order
-
-1. Lock the canonical namespace and package metadata.
-2. Implement the stdio MCP server entrypoint.
-3. Add a minimal `core.health` tool.
-4. Add the first `agenticlens` and `agentic-chaos` adapter-backed tools.
-5. Add examples and publishable packaging checks.
-
 ## What's Next
 
-Upcoming capabilities (see [ROADMAP.md](ROADMAP.md) for full details):
+Phase 2 (session management, rich diagnostics, tool annotations, prompt
+registry, `core.verify`) and Phase 3b (Agentic Chaos) are complete as of
+`0.2.0`. What's still open (see [ROADMAP.md](ROADMAP.md) for full detail):
 
-- **Session management** — sequential tool calls share context without
-  resending artifacts
-- **Rich diagnostics** — `core.health` returns adapter availability, dependency
-  versions, and config validation
-- **Tool annotations** — category, prerequisites, duration, and mutation
-  metadata on every tool
-- **Prompt registry** — reusable prompt templates for analysis, comparison, and
-  experiment workflows
-- **Integration verification** — `core.verify` checks agenticlens and
-  agentic-chaos connectivity
+- **Phase 3a (AgenticLens)** — provenance verification on
+  `lens.analyze_workflow`'s response shape
+- **Phase 3c (AI Operations Specification)** — multi-version schema support
+  and conformance-style reporting, both blocked on upstream `ai-operations-spec`
+  work landing first
+- **Phase 4 (Unified Workflows)** — joined observability + chaos workflows,
+  incident/readiness reporting, a higher-level control surface
+- **Phase 5/6** — PyPI + MCP Registry publishing, operational intelligence
+  features
 
 ## Development
 
@@ -178,6 +186,8 @@ A `Makefile` provides shorthand for common tasks:
 make install     # install dev dependencies
 make check       # run all quality gates (lint + format + typecheck + test)
 make test-cov    # tests with coverage report
+make docs        # regenerate docs/tools.md from tools/registry.py
+make docs-check  # fail if docs/tools.md is out of date
 make help        # list all available targets
 ```