ESAA VS Code Dashboard

Treat LLMs as intention emitters under contract - and make the ESAA state visible inside VS Code.

ESAA VS Code Dashboard is a Visual Studio Code extension that helps you inspect and operate ESAA projects by reading the canonical artifacts in .roadmap/ (especially roadmap.json and activity.jsonl) and presenting them in a developer-friendly dashboard inside the editor.

If you are new to ESAA, start here:
Paper: https://arxiv.org/pdf/2602.23193
Overview: https://www.elzobrito.com/esaa/

What is ESAA (in one paragraph)

ESAA (Event Sourcing for Autonomous Agents) is an architecture for orchestrating autonomous LLM-based agents in software engineering workflows using Event Sourcing: the single source of truth is an immutable append-only event log (activity.jsonl). The current state of the project is a deterministic projection (roadmap.json) verifiable by replay plus hashing. Agents propose; the orchestrator validates and applies effects.

Why this extension?

ESAA is intentionally strict and file-driven. That is great for auditability, but daily work benefits from a UI that makes the state easy to read:

• The ESAA truth is distributed across a small set of canonical artifacts.
• The most important signals (task state, attempts, rejections, verification status) are present, but not always convenient to browse as raw JSON/JSONL.
• A dashboard in VS Code keeps the loop tight while you develop, review, and audit.

What you can do with the Dashboard

Typical workflows supported by this extension:

• Inspect the read-model (.roadmap/roadmap.json) and understand current task states and dependencies.
• Inspect the event store (.roadmap/activity.jsonl) as an append-only timeline.
• Browse dedicated ESAA views in the Activity Bar:
  • Roadmap
  • Timeline & Events
  • Dashboard & Metrics
• Trigger verification with ESAA Verify.

Quickstart (30 seconds)

1. Open a repository that contains an ESAA project (a .roadmap/ folder).
2. Ensure at least these files exist:
   • .roadmap/roadmap.json (or another file matching .roadmap/roadmap.*.json)
   • .roadmap/activity.jsonl
3. Open the ESAA icon in the VS Code Activity Bar.
4. Open the Command Palette:
   • Windows/Linux: Ctrl+Shift+P
   • macOS: Cmd+Shift+P
5. Run: ESAA Verify.

Expected project structure

A typical ESAA layout:

.roadmap/
├── activity.jsonl                 # Event store (append-only, source of truth)
├── roadmap.json                   # Read-model (projection)
├── AGENT_CONTRACT.yaml
├── ORCHESTRATOR_CONTRACT.yaml
├── RUNTIME_POLICY.yaml
├── STORAGE_POLICY.yaml
├── PROJECTION_SPEC.md
├── agents_swarm.yaml
├── specs/
│   └── *.md
└── qa/
    └── *.md
src/
tests/

The dashboard focuses on .roadmap/ because that is where ESAA canonical truth lives.

Commands

Current command surface (from package.json):

• ESAA Verify (esaa.verify)
  Runs validation checks over ESAA artifacts.

• Open Task File (esaa.openTaskFile)
  Opens task-linked files from dashboard interactions.

Internal command:

• esaa.timelineLoadMore is used by the timeline view for pagination and is not typically invoked manually.

Configuration

This version currently does not contribute user settings (contributes.configuration) in package.json.

Screenshots

Add screenshots or GIFs here to match Marketplace expectations.

Example placeholders:

• assets/marketplace/overview.png
• assets/marketplace/events.png
• assets/marketplace/tasks.png

Known limitations

• The dashboard can only reflect what exists in the .roadmap/ artifacts.
• If files are missing or schemas do not match the expected ESAA version, views may show partial data.

Roadmap (extension)

Suggested next steps for the extension:

• Task dependency graph visualization
• Filters (by state, kind, actor, event type)
• Verify summary panel (verify status plus projection hash)
• Quick navigation from a task to its spec/impl files
• Diff view between projection snapshots (time-travel)

License

MIT

Author

Elzo Brito dos Santos Filho
elzo.santos@cps.sp.gov.br