convez.ai
MCP Server
arturcrmbot

zava-control-plane

arturcrmbot/zava-control-plane

Ver no GitHub
InicialPluginScore · de 0 a 100

Composable agentic substrate (skills + MCP tools + harness + governance) running on a single laptop. 14 live business domains, 79 personae, AGT v3.4 governance, OWASP Agentic Top 10 covered. PoC — safe to clone & run locally; gated for public deploy.

Instalação

$npx convez-ai arturcrmbot/zava-control-plane

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
1
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

Zava Control Plane — Apex Substrate

OWASP Agentic AI Top 10 — 10/10 covered License: MIT Status: PoC — runs on a laptop

Walkthrough video (3:42). What the substrate is, a workflow in flight, the authority matrix, agent memory, and the knowledge graph.

Explainer video poster

A composable agentic substrate (skills + MCP tools + harness + governance) running on a single laptop, with multiple business domains composed on top of it. Production-shaped — Microsoft Agent Framework durable workflows for orchestration, GHCP SDK Python for agent identities, a long-lived Fleet Manager session supervising exceptions in real time.

38 live domains (+ the generic policy_set shim = 39 total in api/shared/domains.py) — all spawnable at runtime (the previously-stubbed CEO meta-workflows were filled in by the v1.x wave; employee-transfer and training-request were the most recent additions, both via the compose-domain meta-skill). Two were hand-built (POC1 finance expense-claim, POC2 hiring); the rest were graduated end-to-end by the compose-domain v4 meta-skill. Authoritative count + per-function breakdown lives in docs/ARCHITECTURE.md §2; the table below is a curated subset of headline domains. Every per-domain integration fact (workflow_type, prefix, orchestrator, persona gates, persona, operator surface, wake hints, spawner, realistic cadence) lives in a single registry — api/shared/domains.py — so the substrate's generic layers read every domain at runtime instead of switching on hard-coded literals.

DomainWhere it livesStatus
POC1 — Finance expense complianceapi/functions/workflows/expense_claim.py — 7 phasesLive · 13 ACs, brief in docs/archive/poc1-brief.md
POC2 — HR talent lifecycleapi/functions/workflows/hiring.py — 10 phasesLive · 22 capabilities, archived status in docs/archive/poc2-status.md
Fleet travel pre-approvalapi/functions/workflows/fleet_travel_preapproval.py — 3 phasesComposed · compose-domain v1; first existence proof
Fleet vendor onboarding & KYCapi/functions/workflows/fleet_vendor_kyc.py — 4 phasesComposed · compose-domain v3
Fleet employee onboardingapi/functions/workflows/fleet_employee_onboarding.py — 4 phasesComposed · compose-domain v3
Fleet IT access requestapi/functions/workflows/fleet_it_access_request.py — 5 phasesComposed · compose-domain v3
Fleet contract renewalapi/functions/workflows/fleet_contract_renewal.py — 5 phasesComposed · compose-domain v3
Fleet performance reviewapi/functions/workflows/fleet_perf_review.py — 5 phasesComposed · compose-domain v3
Fleet AP invoiceapi/functions/workflows/fleet_ap_invoice.py — 4 phasesComposed · compose-domain v3
Fleet purchase orderapi/functions/workflows/fleet_purchase_order.py — 4 phasesComposed · compose-domain v3
Fleet contract reviewapi/functions/workflows/fleet_contract_review.py — 4 phasesComposed · compose-domain v3
Fleet privacy DPIAapi/functions/workflows/fleet_privacy_dpia.py — 4 phasesComposed · compose-domain v3
Fleet treasury FXapi/functions/workflows/fleet_treasury_fx.py — 4 phasesComposed · compose-domain v3
Creative campaignapi/functions/workflows/creative_campaign.py — 10 phasesComposed · compose-domain v3

Each domain spawns at its own realistic cadence (realistic_interval_seconds in api/shared/domains.py) scaled by DEMO_TIME_WARP_FACTOR (default 60) — so AP-invoice spawns every ~30s of demo, perf-review effectively dormant. See .env.example.

Hiring (POC2) executes as four agentic segments (B / D / E / F) rather than per-phase activities — the orchestrator hands enriched state to a single goal-shaped agent per segment. See docs/runtime-providers.md for the LLMRuntime Protocol (GHCP + Fake implementations) and api/server/services/governance/permission_handler.py for the AGT pre-tool hook that gates every tool call inside a segment.

The pitch behind this is captured in docs/archive/blueprint.md; the live editorial microsite that visualises the substrate is web/blueprint/, shipped two ways:

See docs/blueprint-microsite-contributor-guide.md for the editorial deploy and §14 of docs/ARCHITECTURE.md for the replay deploy.

Stack

  • Python 3.11 (Functions worker) + 3.13 (FastAPI) · FastAPI · Azure Durable Functions · MAF · GHCP SDK Python
  • React 19 · Vite 6 · TailwindCSS 4 — three frontends: control plane, candidate portal, blueprint microsite
  • 10 Node mock MCP servers (3 finance + 7 HR/comms — see mocks/)
  • Microsoft Agent Governance Toolkit (AGT) v3.4 — in-process policy kernel mediating every MCP tool call, hash-chained signed audit ledger, Ed25519 per-agent identities, operator kill switches. See plan/archive/feature-agent-governance-toolkit-1.md for the full architecture; CI runs agt verify on every PR and publishes an agt-evidence.json artefact.

🟢 Safe to clone & run locally — gated for public deploy

This is a proof of concept designed to run on a single laptop. It is safe to clone, read, and run on localhost. It must NOT be bound to a public network interface (no public Azure App Service ingress, no Container App with external ingress enabled, no exposing port 3101 outside localhost) without first walking the deployment gate below. A POC_UNSAFE_FOR_PUBLIC_DEPLOY=1 marker lives at .poc-safety so any future CI guard can fail a deployment manifest that wires a public ingress while that marker is still present.

Surface inventory

The PoC ships hardening for almost every surface a public deploy would care about. Two of the three originally-listed "still-unsafe" surfaces have shipped fixes; the third is sandboxed but not formally hardened. Status:

SurfaceStatusCode path
find_entities MCP tool✅ Hardened — free-form Cypher removed; only registered, parameter-validated query templates accepted (commit 680282a9)api/server/mcp_tools/find_entities.py, api/server/services/find_patterns.py
POST /api/durable-event internal route✅ Hardened — requires X-Durable-Event-Signature HMAC; secret in DURABLE_EVENT_SECRET (commit 07882946)api/server/routes/internal_durable_event.py, api/server/services/webhook_auth.py
Persona decision_policy exec() loader🟡 Sandboxed — __builtins__ replaced with a 15-symbol whitelist (_DECISION_BUILTINS) blocking __import__, open, eval, exec, compile, getattr/setattr/delattr. AST-level attribute whitelist (blocks __class__/__mro__/__subclasses__ reflection escapes) is the next planned hardening pass.api/server/services/persona_responder.py (_DECISION_BUILTINS line 434)

Hardening switches that exist today

Env flagGatesDefault
CORS_ALLOWED_ORIGINSBrowser-facing CORS allowlist; no wildcard-with-credentials (C3, commit 5271fb94)empty / restrictive
SERVICENOW_WEBHOOK_SECRETHMAC-signed ServiceNow webhook ingress (C5, commit cb5b507c)unset → endpoint refuses
FINANCE_BP_WEBHOOK_SECRETHMAC-signed Finance Business Partner webhook ingress (C5, commit cb5b507c)unset → endpoint refuses
DURABLE_EVENT_SECRETHMAC-signed POST /api/durable-event ingress (C4, commit 07882946)unset → endpoint refuses
READ_ROUTE_AUTHSet to enforce to require an authenticated actor on audit / evals / entities / cities reads (C6, commit c71f590c)off (local PoC)

Deployment gate

Any public binding (Azure App Service public ingress, Container App with public ingress, exposing port 3101 outside localhost) requires all of the following:

  1. All hardening switches in enforce mode — CORS_ALLOWED_ORIGINS set to a non-wildcard origin list, both webhook secrets set, READ_ROUTE_AUTH=enforce, DURABLE_EVENT_SECRET set.
  2. Persona loader hardening complete — the AST-level attribute whitelist landed in persona_responder.py (next planned pass) so sandbox-escape reflection paths (__class__/__mro__/ __subclasses__) are blocked at compile time, not only at builtins-replacement time.
  3. .poc-safety marker removed — delete the POC_UNSAFE_FOR_PUBLIC_DEPLOY=1 line in .poc-safety (or delete the file). A CI guard should fail any deployment manifest with public ingress while that marker is present.

Ports

ServicePortWhat
Vite — Control Plane UI5273Domain-neutral operator surface
Vite — Candidate Portal5274POC2 candidate-facing app + recruiter view
Vite — Blueprint microsite5275Editorial page + live observatory (local dev)
FastAPI3101Fleet Manager, simulator, REST, SSE, blueprint stream
Functions host7071Durable orchestrators + activities
Azurite10000-10002Durable state
Mock MCPs (POC1 finance)4101-4103Workday, Concur, Maconomy
Mock MCPs (POC2 HR + comms)4201-4207Greenhouse, LinkedIn, Workday-HR, Graph, ServiceNow, ACS, HeyGen

Quickstart

Prerequisites: Python 3.11 + 3.13, Node 20+, uv, Azure Functions Core Tools v4.9+, Docker (for Azurite — or npm i -g azurite), GitHub Copilot license (gh auth login).

make install                                   # uv sync + npm install (root, web/portal, web/blueprint)
make funcvenv                                  # Windows: one-time Py 3.11 venv for func
cp local.settings.json.example local.settings.json
cp .env.example .env
gh auth login
make up                                        # boots azurite + POC1 mocks + FastAPI + control-plane UI + portal + functions

UI at http://localhost:5273, candidate portal at http://localhost:5274. The simulator's domain-aware ramp loop trickles real workflows from all 38 live domains into the dashboard automatically when the substrate is up, each at its own realistic cadence (AP-invoice ~every 30s of demo, hiring ~every 24min, perf-review effectively dormant — see api/shared/domains.py; tune via DEMO_TIME_WARP_FACTOR). The persona responder resolves every persona gate autonomously — there is no human in the loop. A small per-gate wait_probability produces visual variety (the gate takes a moment to resolve) but never requires an operator click; personae can also return an escalate verdict for high-risk inputs, which produces an enriched FM exception for visibility. The blueprint microsite runs separately (npm run dev:blueprint → http://localhost:5275); see the contributor guide.

For POC2 mocks (hiring demo): npm run dev:mcp:poc2 in another terminal.

Layout

api/     — Python: FastAPI + Durable Functions + MAF graphs + skills + personae + MCP tools
web/
  client/    — Control Plane UI (operator surface, domain-neutral)
  portal/    — Candidate portal + recruiter view (POC2)
  blueprint/ — Editorial microsite + live observatory of the substrate
mocks/   — 10 Node MCP servers (3 finance + 7 HR/comms)
tests/   — pytest (api/), vitest (web/), Playwright (e2e/)
docs/    — see docs/README.md for the full index
scripts/ — boot-demo.sh, build-blueprint-image.sh, deploy-blueprint.sh, profile-*.sh, blueprint-ticker.sh

Root-level configs (pyproject.toml, package.json, host.json, function_app.py, vite.config.ts, Makefile, docker-compose.yml) serve the whole repo.

More

Stop

Ctrl-C the make up terminal. In-memory Fleet Manager + simulator state clears; Durable Functions state persists in azurite-data/. make reset wipes it between demo takes.

Ver o original no GitHub

Bom para

Relacionados