Enterprise Agent v0.1

Enterprise Agent is a single-tenant enterprise control-plane agent. It is built from scratch while borrowing useful patterns from Hermes Agent and claw-code: memory, skills, subagents, tool registry, Claude-style tool use, explicit permission modes, event replay, approvals, and compensating rollback.

Current Capabilities

• Web Console for task creation, execution trace, tool calls, memory, skills, approvals, rollback, and raw replay payloads.
• CLI for terminal-driven sessions, tasks, memory search, skills, approvals, rollback, replay, audit, providers, tools, and MCP.
• Fastify API Server as the control plane.
• Python FastAPI Agent Runtime with a deterministic v0.1 state machine.
• PostgreSQL + pgvector schema for tasks, events, tool calls, memories, skills, approvals, rollback plans, artifacts, providers, MCP servers, and evaluations.
• Tool manifest registry with risk, environment, approval, rollback metadata, and runtime input/output schema validation.
• Permission modes: read_only, workspace_write, approval_required, admin_full_access.
• Agent run flow: plan -> tool use -> tool result -> memory update -> skill update -> eval -> final.
• Claude-style tool-use message contract.
• Subagent perspectives for operations, product, and engineering.
• Skill/SOP self-evolution with versioned skill_versions.
• Structured event log for replay, debug, and audit.
• Docker Compose development stack.
• Runtime unit tests for state transitions, provider fallback, policy, and MCP mock behavior.
• Session model with sessions, session_messages, and session_task_links.
• Cross-session memory fields: source_session_id, scope, last_used_at.
• Approval resume flow for continuing a persisted plan after approval.
• Replay-critical events for memory.used, skill.used, approval.requested, approval.resumed, rollback.plan_created, rollback.dry_run, and rollback.executed.
• Audit filtering by task, tool, risk, environment, task status, and event type, with JSON or CSV output.
• Replay integrity reporting for missing core timeline events.
• pgvector-ready memory retrieval with a deterministic 1536-dimensional embedding fallback and provider-swap boundary.
• Gated OpenAI-compatible Chat Completions provider adapter path with deterministic fallback when real calls are disabled or unavailable.
• OpenAI-compatible Chat Completions provider path for real LLM planning, including timeout, retry, fallback, rate-limit, usage, and estimated-cost telemetry.
• Web Session Detail, Skill Version governance, and Replay Integrity views.
• Optional API admin bearer-token enforcement with ADMIN_API_TOKEN; CLI uses AGENT_API_TOKEN.
• Minimal single-tenant RBAC with admin, operator, and viewer tokens. Viewers can read, operators can run standard control-plane work, and admin-only endpoints cover approval decisions, provider secret changes, rollback execution, memory disable, and Skill rollback.
• Web Console token login stores the API token locally and sends it through the API Server.
• Encrypted Provider configuration storage with masked secret display and Provider Health views.
• Provider Stats and Tool Call Debug surfaces for usage, fallback, cost, risk, policy decision, approval, and rollback inspection.
• Task event Server-Sent Events stream for real-time execution consumption.
• Runtime structured JSON logs for task events with task_id, session_id, tool_call_id, trace_id, and error category where available.
• Operational endpoints for health, migrations, JSON metrics, and Prometheus metrics: /ops/health, /ops/migrations, /ops/metrics, /ops/metrics/prometheus.
• Skill/SOP self-evolution uses a PostgreSQL transaction advisory lock while allocating versions, preventing concurrent runs from racing the active Skill version.
• GitHub read-only repository status adapter for test/read-only validation through github.get_repo_status, with mock fallback when no repo or token is configured.
• Docker-backed backup and guarded restore scripts: npm run ops:backup, npm run ops:restore -- --check <backup.sql>, and confirmed restore execution.
• Release Candidate validation with npm run release:check covering secret redaction, concurrent tasks, production approval, Runtime restart recovery, approval resume, rollback-plan presence, and metrics.

Release Handoff Docs

• QUICKSTART.md
• SECURITY.md
• CONTRIBUTING.md
• RELEASE_NOTES.md
• CHANGELOG.md
• RUNBOOK.md
• DEPLOYMENT.md
• BACKUP_RESTORE.md
• SECURITY_REVIEW.md
• UAT_REPORT.md
• KNOWN_ISSUES.md
• PRE_RELEASE_CHECKLIST.md
• docs/public-demo.md
• docs/production-notes.md

Public Repository Safety

This repository is intended to be safe for a public GitHub upload after local cleanup.

• Do not commit .env, logs, backups, database dumps, screenshots with secrets, node_modules, .venv, dist, or __pycache__.
• Keep .env.example placeholder-only.
• Mock provider and mock external adapters are the default.
• Real provider keys and external adapter credentials are optional and must stay in .env or a managed secret store.
• Production/high-risk side-effect tools remain approval-gated.

If a real secret was committed to Git history, rotate it and rewrite history or initialize a clean repository before making the repo public.

Requirements

• Docker and Docker Compose
• Node.js 20+
• Python 3.11+ is required only for local Runtime tests; Docker runs the Runtime for the normal quickstart.

Quickstart

For a fresh clone, use the full flow in QUICKSTART.md.

Copy environment variables if you need provider or integration credentials:

cp .env.example .env
npm ci

Start the stack:

docker compose config
docker compose up -d --build

Open:

• Web Console: http://localhost:5173
• API Server: http://localhost:3001/health
• Agent Runtime: http://localhost:8000/health
• PostgreSQL: localhost:55432

Run smoke test after the stack is ready:

npm run smoke
npm run acceptance:workflows
npm run release:check

Set up local Python tests only when you want to run the full test suite outside Docker:

python3.11 -m venv .venv  # or any Python 3.11+ interpreter
.venv/bin/pip install -r services/agent/requirements.txt
npm run test
npm run test:api
npm run test:cli
npm run test:python
npm run build

Run a real OpenAI-compatible provider smoke only when you intentionally want to spend provider credits:

Set these values in .env:

ENABLE_REAL_PROVIDER_CALLS=true
LLM_PROVIDER=OpenAI
LLM_API_KEY=<provider_key>
LLM_MODEL=<model>
LLM_BASE_URL=<chat_completions_url>

Then run:

docker compose up -d --force-recreate agent-runtime api web
npm run smoke:real-provider

# Restore keyless deterministic fallback mode after verification.
docker compose up -d --force-recreate agent-runtime api web

Run local checks without Docker:

python3.11 -m venv .venv
.venv/bin/pip install -r services/agent/requirements.txt
npm run typecheck --workspace @enterprise-agent/api
npm run typecheck --workspace @enterprise-agent/web
npm run build --workspace @enterprise-agent/api
npm run build --workspace @enterprise-agent/web
PYTHONPATH=services/agent .venv/bin/pytest services/agent/tests -q

CLI

All CLI commands call the API Server. The CLI never connects directly to PostgreSQL or the Agent Runtime.

npm run cli -- health
npm run cli -- session create "My CLI session"
npm run cli -- session list
npm run cli -- chat
npm run cli -- task create "Generate a strategy critique" --description "Use subagents and memory"
npm run cli -- task run <task_id>
npm run cli -- task replay <task_id>
npm run cli -- memory search "Smoke"
npm run cli -- memory list --scope session --session <session_id>
npm run cli -- skill list
npm run cli -- skill show <skill_id>
npm run cli -- skill version <skill_id> <version>
npm run cli -- skill rollback <skill_id> --to <version>
npm run cli -- approvals list
npm run cli -- approvals approve <approval_id>
npm run cli -- rollback dry-run <rollback_plan_id>
npm run cli -- rollback execute <rollback_plan_id>
npm run cli -- audit --tool github.merge_pr --risk high --env production
npm run cli -- audit --format csv
npm run cli -- providers health
npm run cli -- providers stats
npm run cli -- providers config openai --model gpt-4.1-mini --api-key <test_key>
npm run cli -- tool-debug <tool_call_id>
npm run cli -- ops health
npm run cli -- ops metrics
npm run cli -- ops migrations
curl http://localhost:3001/ops/metrics/prometheus

Stop:

docker compose down

Development Commands

npm run dev
npm run logs
npm run down
npm run smoke

v0.1 Boundaries

The agent may self-evolve only these assets:

• Skill
• SOP
• workflow template
• prompt guidance
• tool usage experience
• pitfall knowledge base
• task artifacts

It must not self-modify:

• platform source code
• backend control-plane logic
• database schema
• Web Console code

Real Integrations

The current code includes safe adapter boundaries for Lark, Telegram, GitHub/GitLab, Supabase, and MCP. If credentials are absent, calls produce structured mock results while preserving event logs, policy decisions, rollback plans, and auditability. Real adapters should replace the mocked execution branch behind the existing manifest and policy contracts.

Current Score

Current implementation score against the enterprise-agent target: 98/100.

The latest hardening pass moved the project beyond the previous 55/100 control-plane slice by making the replay/audit/rollback path stricter:

• high-risk approval gates emit explicit replay events
• side-effect tools emit rollback plan creation events
• rollback dry-runs are audit-visible events
• tool input/output schemas are enforced in the runtime
• audit supports task/tool/risk/environment/status/event filters and CSV export
• Web Console exposes rollback dry-run results before execution
• memory search/list supports session, scope, and type filters
• skill detail exposes version history with previous version links and explicit target rollback
• replay integrity is computed by the runtime and displayed in the Web Console
• generated memories store embedding metadata and pgvector-compatible vectors
• root test scripts now cover Python runtime, API contract, and CLI smoke paths
• provider routing has a gated OpenAI-compatible adapter path while preserving deterministic fallback for keyless test runs
• API access can be protected with an admin token without breaking local keyless development
• provider API keys are encrypted at rest in provider_configs.metadata and never returned by API/CLI
• Web Console shows Provider Health and Provider Configs
• /tasks/:id/events/stream exposes replayable task events as SSE for real-time control-plane consumers
• OpenAI-compatible real-provider smoke has been verified against a compatible chat-completions endpoint: real planning response, real token usage, provider event, tool execution, task completion, and replay integrity.
• provider failures now degrade through typed fallback telemetry unless fallback is explicitly disabled
• Docker Compose passes non-secret provider configuration into the runtime, relies on .env/env_file for provider secrets, and adds healthchecks for Runtime, API, Web, and PostgreSQL
• /ops/health, /ops/migrations, and /ops/metrics expose DB, Runtime, Provider, MCP, migration, queue-mode, task, tool-call, approval, and rollback operational status
• task event payloads and structured logs redact API keys, tokens, passwords, authorization headers, and secrets before persistence or stdout logging
• 5 benchmark workflows now have a repeatable acceptance script: bugfix + HTML artifact, Lark report, subagent critique, Skill/SOP update, and rollback dry-run/execute plus Skill rollback.
• /providers/stats summarizes provider usage and fallback telemetry from append-only task events.
• /tool-calls/:id/debug exposes input, output, duration, manifest, policy decision, approvals, rollback plans, and linked events.
• /skills/:id/versions/:version/diff exposes Skill/SOP version diffs for governance review.
• MCP mock gateway now defaults new servers to untrusted until their permission manifest explicitly sets trusted and allowed_tools.
• Skill/SOP version allocation is serialized with a Postgres advisory transaction lock, closing the concurrent self-evolution race found during smoke plus workflow acceptance.
• Prometheus-format metrics are available for API and Runtime counters.
• Secret-like strings are redacted from Runtime logs/events, persisted tool calls, rollback plans, approval payloads, task results, API-created event payloads, and API responses used by Web/CLI.
• Policy now distinguishes no-side-effect read/analyze tools from side-effect tools in production/high-risk tasks; side-effect and production/high-risk tools remain approval-gated.
• npm run release:check verifies concurrent task execution, secret redaction, production SQL approval, Runtime restart recovery, persisted approval resume, rollback-plan presence, and metrics.
• Backup uses pg_dump --clean --if-exists; guarded restore supports --check, explicit confirmation, and was verified in an isolated Compose restore drill.
• A real GitHub read-only workflow was verified against a public repository using GITHUB_READONLY_REPO and a read-only token boundary; no production write operation is connected.

Still mocked: external Lark, Telegram, GitHub/GitLab, Supabase, and MCP execution. Embeddings currently use deterministic local fallback vectors unless replaced by a real embedding provider. LLM calls default to deterministic fallback unless ENABLE_REAL_PROVIDER_CALLS=true and a provider key is configured.

Security / Operations

• Set ADMIN_API_TOKEN, OPERATOR_API_TOKEN, and VIEWER_API_TOKEN on the API service to enable RBAC. When no tokens are set, local development runs as admin.
• Set AGENT_API_TOKEN for the CLI to whichever role token the operator should use.
• Set AUTH_TOKEN_EXPIRES_AT to an ISO timestamp for production trial token expiry.
• Set APP_SECRET_KEY to a stable high-entropy value before storing provider secrets. The local default exists only for development.
• This RC has no password database or JWT session store. If password login is added later, passwords must be hashed with bcrypt or stronger; for this release, use expiring bearer tokens behind a trusted network boundary or reverse proxy.
• Provider API keys can be configured through API/CLI and are stored encrypted with AES-256-GCM in PostgreSQL metadata.
• Use npm run cli -- ops health for a single deploy-readiness check across API, Runtime, DB, providers, migrations, queue mode, and MCP boundary.
• Use npm run cli -- ops metrics for current task/tool/approval/rollback counters.

Deployment Runbook

Local deployment:

cp .env.example .env
npm ci
docker compose config
docker compose up -d --build
npm run smoke
npm run acceptance:workflows
npm run release:check
npm run ops:backup

Cloud VM deployment:

cp .env.example .env
# Set POSTGRES_PASSWORD, APP_SECRET_KEY, ADMIN_API_TOKEN, and any test provider keys.
docker compose up -d --build
npm run cli -- ops health
npm run acceptance:workflows
npm run release:check

Upgrade:

docker compose config
docker compose build --dry-run
docker compose up -d --build
npm run smoke
npm run release:check

Backup and restore:

npm run ops:backup
npm run ops:restore -- --check backups/enterprise-agent-<timestamp>.sql
CONFIRM_RESTORE=I_UNDERSTAND_THIS_OVERWRITES_DATABASE npm run ops:restore -- backups/enterprise-agent-<timestamp>.sql

Read-only GitHub verification:

GITHUB_READONLY_REPO=openai/openai-python \
GITHUB_READONLY_TOKEN=<readonly_token> \
docker compose up -d --force-recreate agent-runtime api web