Docs/ecosystem agents context

AGENTS.md

@@ -1,5 +1,57 @@
 ## deep-agentic-core-mcp Development Reference
 
+## Ecosystem Context
+
+### Role in DeepAgentLabs
+
+`deep-agentic-core-mcp` is the MCP-native control surface for DeepAgentLabs. It
+exposes spec-aligned operational artifacts and selected capabilities from the
+ecosystem through a unified interface for hosts, agents, and external systems.
+
+### Owns
+
+- MCP server wiring, handler registration, tool/resource exposure, and transport
+  boundaries
+- Thin orchestration that composes capabilities from sibling packages without
+  redefining their core logic
+- The contract for how DeepAgentLabs capabilities are presented through MCP
+
+### Does Not Own
+
+- The canonical operational model or schema definitions — those belong in
+  `ai-operations-spec`
+- Primary instrumentation, trace analysis, or evaluation logic — those belong
+  in `agenticlens`
+- Fault injection and resilience simulation logic — those belong in
+  `agentic-chaos`
+- Agent-decision supervision or governance policy logic — those belong in
+  `agentic-sidecar`
+
+### Integrates With
+
+- `ai-operations-spec` so returned artifacts and tool semantics align with the
+  shared contract
+- `agenticlens` as a source of analysis, provenance, and workflow evidence
+- `agentic-chaos` as a source of resilience and degradation workflows
+- `agentic-sidecar` when supervised-decision capabilities need MCP exposure in
+  the future
+
+### Current Roadmap Focus
+
+The next major work is provenance verification on `lens.analyze_workflow`,
+multi-version AIOS schema support, and more unified observability-plus-chaos
+workflows. Changes here should strengthen composition and interoperability, not
+duplicate implementation logic from sibling repos.
+
+### Before You Build Here
+
+- Prefer adapting and exposing sibling-package behavior over rebuilding it in
+  server-local modules
+- If a new concept changes artifact meaning or shape across the ecosystem,
+  update `ai-operations-spec` first
+- Keep this package thin: MCP is the access layer, not the place to invent a
+  second analysis engine, chaos engine, or policy runtime
+
 ## Build and Run
 
 - Install: `make install` (runs `uv sync --extra dev`)

README.md

@@ -5,6 +5,7 @@ ecosystem. It is designed to expose a single MCP interface that combines:
 
 - `agenticlens` style workflow inspection, profiling, and analysis
 - `agentic-chaos` style resilience testing and fault-injection workflows
+- `agentic-sidecar` style supervision-readiness and module-surface discovery
 
 It sits above the **AI Operations Workflow Specification**, exposing a unified
 MCP-native control surface over the shared operational model used by the
@@ -22,11 +23,12 @@ libraries:
 
 - `agenticlens` remains the core profiling and analysis engine
 - `agentic-chaos` remains the core chaos and resilience engine
+- `agentic-sidecar` remains the core decision-supervision and governance engine
 - the `AI Operations Workflow Specification` remains the shared data contract
 - `deep-agentic-core-mcp` becomes the MCP-native interface that hosts can call
 
-That means MCP clients can connect once and access both observability and chaos
-testing capabilities through one server.
+That means MCP clients can connect once and access observability, chaos, and
+sidecar discovery capabilities through one server.
 
 ## What This Server Should Eventually Do
 
@@ -35,6 +37,8 @@ Planned capability areas:
 - profile an agentic workflow and return structured telemetry summaries
 - analyze workflow artifacts and surface optimization recommendations
 - run controlled chaos experiments against target workflows
+- expose sidecar readiness and scaffold inventory while the upstream runtime
+  is still under construction
 - compare normal versus chaos runs
 - expose shared resources such as workflow schemas, run metadata, and saved
   reports
@@ -43,8 +47,8 @@ Planned capability areas:
 
 - One MCP identity: publish a single server to the MCP Registry
 - Python-first: package and publish through PyPI
-- Thin orchestration layer: reuse `agenticlens` and `agentic-chaos` instead of
-  re-implementing their logic
+- Thin orchestration layer: reuse `agenticlens`, `agentic-chaos`, and
+  `agentic-sidecar` instead of re-implementing their logic
 - 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,
@@ -56,7 +60,7 @@ Planned capability areas:
 - `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
+- `core.verify` — checks agenticlens/agentic-chaos/agentic-sidecar/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
@@ -70,6 +74,10 @@ Planned capability areas:
 - `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))
+- `sidecar.status` — report whether `agentic-sidecar` is connected and
+  whether its runtime is implemented yet
+- `sidecar.module_inventory` — inspect the current scaffolded sidecar
+  modules, framework adapters, and integration placeholders
 - `spec.validate_artifact` — validate a workflow/run artifact against the AI
   Operations v0.4 draft
 
@@ -120,13 +128,15 @@ mcp-server/
 │       │   ├── __init__.py
 │       │   ├── agentic_chaos.py
 │       │   ├── agenticlens.py
+│       │   ├── agentic_sidecar.py
 │       │   └── ai_operations_spec.py
 │       └── tools/
 │           ├── __init__.py
 │           ├── registry.py
 │           ├── chaos.py
 │           ├── core.py
 │           ├── lens.py
+│           ├── sidecar.py
 │           └── spec.py
 └── tests/
     ├── test_degraded_boot.py
@@ -149,8 +159,9 @@ MCP server:
 - `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
+  `agentic-sidecar`, and `ai-operations-spec` — each degrades to
+  `"available": false` rather than crashing server boot if its sibling repo is
+  missing
 
 ## Packaging and Publishing Model
 
@@ -170,6 +181,9 @@ registry, `core.verify`) and Phase 3b (Agentic Chaos) are complete as of
 
 - **Phase 3a (AgenticLens)** — provenance verification on
   `lens.analyze_workflow`'s response shape
+- **Phase 3d (Agentic Sidecar Discovery)** — now implemented in the current
+  development line; richer sidecar control surfaces still depend on upstream
+  runtime milestones landing first
 - **Phase 3c (AI Operations Specification)** — multi-version schema support
   and conformance-style reporting, both blocked on upstream `ai-operations-spec`
   work landing first

ROADMAP.md

@@ -15,6 +15,9 @@ Current shipped version: `0.2.0` (2026-08-08) — see [CHANGELOG.md](CHANGELOG.m
   `lens.slo_summary`, and `lens.audit_report` shipped in `0.2.0`
 - **Phase 3b: Agentic Chaos Integration** ✅ Complete — `chaos.list_faults`
   shipped in `0.1.3`; `chaos.run_experiment` shipped in `0.2.0`
+- **Phase 3d: Agentic Sidecar Discovery** ✅ Complete — `sidecar.status`
+  and `sidecar.module_inventory` ship in the current development line as
+  MCP-visible discovery/readiness tools
 - **Phase 3c: AI Operations Specification Conformance** 🏗️ In progress —
   `spec.validate_artifact` and schema resources shipped in `0.1.3`, ahead of
   where this roadmap originally planned them; remaining work still blocked on
@@ -34,6 +37,11 @@ status should explicitly account for upstream and downstream dependencies.
 - `agentic-chaos`
   Provides resilience/fault injection behavior surfaced through `chaos.*`
   tools.
+- `agentic-sidecar`
+  Provides decision-supervision and governance behavior. Today the MCP server
+  only exposes discovery/readiness information because the sidecar runtime is
+  still scaffold-only upstream; richer `sidecar.*` control surfaces depend on
+  that package shipping real runtime behavior first.
 - `ai-operations-spec`
   Provides the canonical artifact model and validation rules surfaced through
   `spec.*` tools and used as the ecosystem exchange contract.
@@ -69,6 +77,7 @@ Build one public MCP server for the DeepAgentLabs ecosystem that unifies:
 
 - workflow observability from `agenticlens`
 - resilience testing from `agentic-chaos`
+- decision-supervision surfaces from `agentic-sidecar`
 
 The result should feel like a coherent platform surface rather than two loosely
 connected products.
@@ -77,6 +86,7 @@ The product boundary should mirror the PyPI ecosystem:
 
 - `agenticlens` observes, evaluates, explains, and recommends
 - `agentic-chaos` injects, validates, tests, and proves resilience
+- `agentic-sidecar` governs, challenges, and escalates agent decisions
 - `deep-agentic-core-mcp` exposes those capabilities through one MCP-native
   control surface
 
@@ -88,6 +98,7 @@ eventually make it easy to:
 - analyze prompts, tools, and retrieval
 - compare workflows
 - run chaos experiments
+- inspect sidecar readiness and governance surface
 - summarize incidents and reliability findings
 - expose readiness evidence through one MCP-native interface
 
@@ -157,8 +168,8 @@ Goals:
 - ✅ implement prompt registry support — `prompts/list`/`prompts/get` are wired
   into the server, with real arguments and rendered templates
 - ✅ add integration verification flow — a `core.verify` tool that checks
-  agenticlens, agentic-chaos, and ai-operations-spec connectivity and reports
-  readiness
+  agenticlens, agentic-chaos, agentic-sidecar, and ai-operations-spec
+  connectivity and reports readiness
 
 Success criteria:
 
@@ -244,6 +255,32 @@ Success criteria:
   pattern; tracked as a prerequisite for widening `chaos.run_experiment`
   exposure beyond trusted local stdio clients (see Known Limitations)
 
+## Phase 3d: Agentic Sidecar Discovery
+
+Status: complete in the current development line. `agentic-sidecar` is still a
+scaffold upstream, so this phase intentionally exposes discovery/readiness
+information rather than pretending a decision runtime already exists.
+
+Goals:
+
+- wire `agentic-sidecar` into the MCP server through a degrading adapter
+- expose a first `sidecar.*` surface that is honest about scaffold vs runtime
+- let MCP hosts discover the sidecar module/adapters/integrations footprint
+  without importing the sibling repo themselves
+
+Tools:
+
+- [x] `sidecar.status`
+- [x] `sidecar.module_inventory`
+
+Success criteria:
+
+- `core.verify` and `core.health` report `agentic-sidecar` separately from the
+  other siblings
+- MCP clients can distinguish "package importable" from "runtime implemented"
+- the server surfaces current scaffold inventory without reimplementing sidecar
+  logic locally
+
 ## Phase 3c: AI Operations Specification Conformance
 
 Status: in progress — delivered ahead of where this roadmap had it planned.

docs/tools.md

@@ -3,7 +3,7 @@
 
 # Tool Reference
 
-12 tools, generated from `tools/registry.py` - the same data MCP
+14 tools, generated from `tools/registry.py` - the same data MCP
 clients see via `tools/list`. See [README.md](../README.md) for a one-line-per-tool
 overview and [ROADMAP.md](../ROADMAP.md) for what's shipped per phase.
 
@@ -58,7 +58,7 @@ Input schema:
 
 ### `core.verify` — Verify Integrations
 
-Check connectivity to agenticlens, agentic-chaos, and ai-operations-spec, and report readiness.
+Check connectivity to agenticlens, agentic-chaos, agentic-sidecar, and ai-operations-spec, and report readiness.
 
 | | |
 | --- | --- |
@@ -339,6 +339,50 @@ Input schema:
 }
 ```
 
+## Agentic Sidecar (`sidecar.*`)
+
+### `sidecar.module_inventory` — Sidecar Module Inventory
+
+List the current scaffolded modules, framework adapters, and integration placeholders present in agentic-sidecar.
+
+| | |
+| --- | --- |
+| Category | `sidecar` |
+| Prerequisites | `agentic_sidecar` |
+| Expected duration | instant |
+| Mutates session | no |
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {},
+  "additionalProperties": false
+}
+```
+
+### `sidecar.status` — Sidecar Status
+
+Report whether agentic-sidecar is importable and whether its decision runtime is actually ready yet.
+
+| | |
+| --- | --- |
+| Category | `sidecar` |
+| Prerequisites | `agentic_sidecar` |
+| Expected duration | instant |
+| Mutates session | no |
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {},
+  "additionalProperties": false
+}
+```
+
 ## AI Operations Specification (`spec.*`)
 
 ### `spec.validate_artifact` — Validate AI Operations Artifact

pyproject.toml

@@ -77,6 +77,7 @@ mypy_path = "src"
 module = [
   "agenticlens.*",
   "agentic_chaos.*",
+  "agentic_sidecar.*",
 ]
 ignore_missing_imports = true
 

scripts/generate_tools_doc.py

@@ -25,11 +25,12 @@
 # (a category added to registry.py without updating this map) still renders,
 # alphabetically, at the end - so a new category can't silently vanish from
 # the doc, it just looks less polished until this map is updated too.
-_CATEGORY_ORDER = ["core", "lens", "chaos", "spec"]
+_CATEGORY_ORDER = ["core", "lens", "chaos", "sidecar", "spec"]
 _CATEGORY_TITLES = {
     "core": "Core",
     "lens": "AgenticLens (`lens.*`)",
     "chaos": "Agentic Chaos (`chaos.*`)",
+    "sidecar": "Agentic Sidecar (`sidecar.*`)",
     "spec": "AI Operations Specification (`spec.*`)",
 }