anisharun412/operatingagent

Purpose and Current Maturity

This monorepo is scaffolded for a desktop autonomous AI operating agent. It will execute multi-step local-machine goals through sandboxed MCP tools and compare two interchangeable orchestration implementations: native Plan-and-Execute/ReAct versus LangGraph. Most runtime packages currently expose only package initializers/placeholders, so the intended architecture is clearer than the implemented application surface.

Entry Points and Execution Surfaces

Python services and agents are independently launched from the uv workspace:

• API: intended FastAPI entry point api.main:app, although no main.py exists yet under packages/api/src/api/.

• Native agent module: packages/agent-native/src/agent_native/__init__.py.

• LangGraph agent module: packages/agent-langgraph/src/agent_langgraph/__init__.py.

• MCP servers run as separate Python modules, e.g. packages/mcp-servers/file-server/src/file_server/__init__.py.

The desktop and frontend directories exist but are placeholders: apps/desktop/__placeholder__.txt, apps/frontend/__placeholder__.txt.

Shared Agent Contract Layer

packages/common is the architectural seam intended to keep both agent tracks behaviorally comparable and tool-agnostic. It contains shared agent abstractions, interfaces, tool definitions, events, configuration, enums, and exceptions:

• packages/common/src/common/agent.py

• packages/common/src/common/interfaces.py

• packages/common/src/common/tools.py

• packages/common/src/common/events.py

Both orchestration implementations should consume these contracts rather than directly coupling to a specific tool process or UI.

Parallel Orchestration Tracks

The comparison’s central boundary is between two agent runtimes operating over the same MCP-exposed tool layer:

• Native Plan-and-Execute plus ReAct: packages/agent-native/src/agent_native/__init__.py

• LangGraph StateGraph: packages/agent-langgraph/src/agent_langgraph/__init__.py

Expected flow is goal input → planning → iterative tool selection/execution → verification → result/events. Deterministic risk classification and verification are MVP requirements, but their concrete implementations are not yet present.

MCP Tool Boundary and Sandboxed Execution

Tools are isolated as standalone FastMCP server packages, allowing either agent to invoke identical capabilities through a process/protocol boundary:

• File operations: packages/mcp-servers/file-server/src/file_server/__init__.py

• Terminal execution: packages/mcp-servers/terminal-server/src/terminal_server/__init__.py

• Git operations: packages/mcp-servers/git-server/src/git_server/__init__.py

• Search: packages/mcp-servers/search-server/src/search_server/__init__.py

The sandbox wrapper is the intended containment boundary for local execution: packages/sandbox/src/sandbox/__init__.py. Docker sandbox images are planned at infra/sandbox-images/__placeholder__.txt.

API, Desktop, and Observability Boundaries

The intended API package mediates clients and agent execution: packages/api/src/api/__init__.py. A Tauri desktop shell and separate React track UIs are described in the README, but this tree has only placeholder app directories, so no client/backend contract exists yet.

Observability is isolated for OpenTelemetry and Langfuse instrumentation:

• packages/observability/src/observability/__init__.py

• infra/docker/langfuse/__placeholder__.txt

Evaluation and Supporting Infrastructure

The evaluation package is intended to benchmark orchestration overhead, latency, reliability, and code volume across the two agent tracks: packages/evaluation/src/evaluation/__init__.py. Planned persistent/telemetry infrastructure includes PostgreSQL, Qdrant, and Langfuse:

• infra/docker/postgres/__placeholder__.txt

• infra/docker/qdrant/__placeholder__.txt

• infra/docker/langfuse/__placeholder__.txt

Knowledge and memory MCP servers are Phase 2 extensions, separating semantic memory/RAG from the MVP execution path: packages/mcp-servers/knowledge-server/src/knowledge_server/__init__.py, packages/mcp-servers/memory-server/src/memory_server/__init__.py.