multiagentos 0.4.2__tar.gz → 0.5.0__tar.gz

multiagentos-0.5.0/PKG-INFO

@@ -0,0 +1,617 @@
+Metadata-Version: 2.4
+Name: multiagentos
+Version: 0.5.0
+Summary: Local-first, GitHub-native multi-agent development orchestration runtime
+Project-URL: Homepage, https://github.com/eaglesjo/MultiAgentOS
+Project-URL: Repository, https://github.com/eaglesjo/MultiAgentOS
+Project-URL: Documentation, https://github.com/eaglesjo/MultiAgentOS/tree/main/docs
+Project-URL: Changelog, https://github.com/eaglesjo/MultiAgentOS/blob/main/CHANGELOG.md
+Project-URL: Download, https://pypi.org/project/multiagentos/#files
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: chatgpt
+Requires-Dist: openai>=1.0; extra == "chatgpt"
+Provides-Extra: mcp-http
+Requires-Dist: mcp<3,>=2.2; extra == "mcp-http"
+Requires-Dist: uvicorn>=0.30; extra == "mcp-http"
+
+# MultiAgentOS
+
+> **Local-first, GitHub-native Agent Execution Runtime**
+
+Build, inspect, patch, test, and operate real software projects through an AI-native execution boundary.
+
+MultiAgentOS connects an AI client to a real project workspace while keeping **filesystem, patch, process, Git, and verification authority inside the Agent Execution Runtime**.
+
+---
+
+## Why MultiAgentOS?
+
+AI clients provide reasoning, intent, plans, and results.
+
+**MultiAgentOS provides the execution boundary.**
+
+```mermaid
+flowchart TB
+    CLIENT["AI Client"] --> MCP["MCP"]
+    MCP --> RUNTIME["Agent Execution Runtime"]
+    RUNTIME --> FS["Filesystem"]
+    RUNTIME --> PATCH["Patch"]
+    RUNTIME --> PROCESS["Process"]
+    RUNTIME --> GIT["Git"]
+    FS --> PROJECT["Real Project"]
+    PATCH --> PROJECT
+    PROCESS --> PROJECT
+    GIT --> PROJECT
+    PROJECT --> GH["GitHub Repository"]
+```
+
+This separation makes local project execution explicit, inspectable, and policy-controlled instead of giving an AI client unrestricted operating-system access.
+
+---
+
+## Core Capabilities
+
+| Capability | What it provides |
+| --- | --- |
+| **Agent Execution Runtime** | Durable execution and permission boundary for real project work |
+| **MCP** | Standard AI-to-runtime tool interface |
+| **Filesystem** | Project file READ / WRITE |
+| **Patch** | Structured source changes through `patch.apply` |
+| **Process** | Internal runtime capability; not part of the current ChatGPT Free verified client path |
+| **Git** | Repository-aware development operations |
+| **GitHub** | Remote repository and collaboration workflow |
+| **Project Isolation** | Independent MCP services and lifecycle per project |
+| **Secure MCP Tunnel** | Optional remote transport for supported clients |
+
+Write and process capabilities are explicit opt-ins. The default MCP surface is read-only.
+
+---
+
+## Architecture
+
+### Local-first execution
+
+```mermaid
+flowchart TB
+    CLIENT["AI Client"] --> MCP["MCP"]
+    MCP --> RUNTIME["Agent Execution Runtime"]
+
+    RUNTIME --> FS["Filesystem"]
+    RUNTIME --> PATCH["Patch"]
+    RUNTIME --> PROCESS["Process / Tests"]
+    RUNTIME --> GIT["Git"]
+
+    FS --> PROJECT["Local Project"]
+    PATCH --> PROJECT
+    PROCESS --> PROJECT
+    GIT --> PROJECT
+
+    PROJECT --> GH["GitHub Repository"]
+```
+
+The local MCP server remains on loopback. The AI client does not receive unrestricted operating-system access; execution is mediated by the runtime policy.
+
+### Multi-agent execution
+
+```mermaid
+flowchart LR
+    REQUEST["Request"] --> ORCH["Orchestrator"]
+    ORCH --> WORKFLOW["MultiAgentWorkflow"]
+
+    WORKFLOW --> DEV["Developer"]
+    WORKFLOW --> TEST["Tester"]
+    WORKFLOW --> REVIEW["Reviewer"]
+
+    REVIEW --> DECISION{"Review passed?"}
+    DECISION -->|No| REWORK["Rework"]
+    REWORK --> DEV
+    DECISION -->|Yes| VERIFY["Verification"]
+
+    VERIFY --> RUNTIME["Agent Execution Runtime"]
+```
+
+`Orchestrator.run_workflow()` is the higher-level orchestration entry point. `MultiAgentWorkflow` owns stage, handoff, review, and rework semantics.
+
+The runtime remains the authority for permissions and execution.
+
+### Governance contracts
+
+MultiAgentOS keeps execution governance inside its own provider-neutral runtime contracts.
+
+```mermaid
+flowchart TB
+    WU["WorkUnit"] --> SCOPE["Scope Lock"]
+    WU --> ROLES["Execution roles"]
+    WU --> ART["Artifacts"]
+    WU --> EVID["Evidence"]
+    WU --> APPROVAL["Human approval"]
+    WU --> HOLD["HOLD safety"]
+
+    SCOPE --> RUNTIME["MultiAgentOS Runtime"]
+    ROLES --> RUNTIME
+    ART --> RUNTIME
+    EVID --> RUNTIME
+    APPROVAL --> RUNTIME
+    HOLD --> RUNTIME
+
+    RUNTIME --> TOOLS["MCP / Filesystem / Process / Git / GitHub"]
+```
+
+These governance contracts are native to MultiAgentOS; they are not dependent on another repository or project-specific Agent OS.
+
+---
+
+### Agent taxonomy and specialist routing
+
+MultiAgentOS separates **Governance / Execution** from platform-oriented specialist agents.
+
+~~~mermaid
+flowchart TB
+    TASK["Task"]
+
+    TASK --> GOV["Governance / Execution"]
+    TASK --> RESEARCH["Research"]
+    TASK --> DEVELOPMENT["Development"]
+    TASK --> UI["UI"]
+
+    GOV --> FILE["File Picker"]
+    GOV --> PLAN["Planner"]
+    GOV --> EDIT["Editor"]
+    GOV --> EXEC["Executor"]
+    GOV --> REVIEW["Reviewer"]
+
+    RESEARCH --> DEV_R["Development Research"]
+    RESEARCH --> UI_R["UI Research"]
+
+    DEV_R --> REACT_R["React"]
+    DEV_R --> RN_R["React Native"]
+    DEV_R --> ANDROID_R["Android"]
+    DEV_R --> IOS_R["iOS"]
+
+    UI_R --> WEB_R["Web UI / React"]
+    UI_R --> RN_UI_R["React Native UI"]
+    UI_R --> ANDROID_UI_R["Android UI"]
+    UI_R --> IOS_UI_R["iOS UI"]
+
+    DEVELOPMENT --> REACT_D["React Developer"]
+    DEVELOPMENT --> RN_D["React Native Developer"]
+    DEVELOPMENT --> ANDROID_D["Android Developer"]
+    DEVELOPMENT --> IOS_D["iOS Developer"]
+
+    UI --> WEB["Web"]
+    UI --> CROSS["Cross-platform"]
+    UI --> NATIVE["Native"]
+    NATIVE --> ANDROID["Android"]
+    NATIVE --> IOS["iOS"]
+~~~
+
+A platform-aware development task can therefore run current platform research before implementation:
+
+~~~mermaid
+flowchart LR
+    TASK["Platform Development"] --> PLAN["Planner"]
+    PLAN --> RESEARCH["Development Research"]
+    RESEARCH --> DEV["Platform Developer"]
+    DEV --> EDIT["Editor"]
+    EDIT --> EXEC["Executor"]
+    EXEC --> REVIEW["Reviewer"]
+~~~
+
+UI work similarly runs UI research before implementation and uses Browser Agent only where browser validation is relevant.
+
+See [Agent Taxonomy and Routing](docs/AGENT_TAXONOMY.md) and [Agent Catalog](docs/AGENT_CATALOG.md).
+
+## GitHub + Local Project
+
+MultiAgentOS treats the remote repository and the local working tree as complementary development surfaces.
+
+```mermaid
+flowchart TB
+    CLIENT["AI Client"]
+
+    CLIENT --> GH["GitHub Repository"]
+    CLIENT --> MCP["Local MCP"]
+
+    MCP --> RUNTIME["Agent Execution Runtime"]
+    RUNTIME --> PROJECT["Local Project"]
+```
+
+The GitHub path provides durable repository state.
+
+The local MCP path provides controlled access to the actual working tree.
+
+These are separate capabilities and can be used independently.
+
+---
+
+## ChatGPT Web in the Verified Setup
+
+The current development environment has verified the following client boundary:
+
+| Client | GitHub | Local MultiAgentOS MCP | Status |
+| --- | --- | --- | --- |
+| **ChatGPT Web** | Yes | Yes | **Verified** |
+| **ChatGPT Mobile App** | Yes | No | **Verified** |
+| **ChatGPT Desktop** | Not evaluated | Not evaluated | Outside current scope |
+
+This is a compatibility record for the verified environment, **not a universal guarantee for every ChatGPT account, plan, or future client build**.
+
+> **Execution boundary:** Process/shell execution is not currently part of the verified ChatGPT Free client path. The runtime contains process-capability infrastructure, but README support claims are limited to capabilities actually exposed and verified through the target client path.
+
+The cost-free local workflow does not depend on Secure MCP Tunnel:
+
+```mermaid
+flowchart TB
+    WEB["ChatGPT Web"]
+
+    WEB -->|GitHub connection| GH["GitHub Repository"]
+    WEB -->|Local MCP| MCP["127.0.0.1:8000/mcp"]
+    MCP --> PROJECT["Local Project"]
+```
+
+---
+
+## Secure MCP Tunnel
+
+Secure MCP Tunnel is an **optional remote connectivity layer** for supported clients that need to reach a private local MCP server.
+
+```mermaid
+flowchart TB
+    CLIENT["Supported Remote Client"]
+    TUNNEL["OpenAI Secure MCP Tunnel"]
+    TC["tunnel-client"]
+    MCP["MultiAgentOS MCP"]
+    RUNTIME["Agent Execution Runtime"]
+    PROJECT["Local Project"]
+
+    CLIENT --> TUNNEL
+    TUNNEL --> TC
+    TC --> MCP
+    MCP --> RUNTIME
+    RUNTIME --> PROJECT
+```
+
+The local MCP server can remain loopback-only. The tunnel client establishes the outbound connection.
+
+### Important boundary
+
+A healthy tunnel proves that the **tunnel infrastructure is connected**. It does not by itself prove that a particular ChatGPT account or plan can invoke every MCP capability.
+
+For the current cost-free baseline:
+
+| Layer | State |
+| --- | --- |
+| Agent Execution Runtime | **PASS** |
+| Local MCP | **PASS** |
+| Secure MCP Tunnel lifecycle | **READY** |
+| Control-plane polling | **PASS** |
+| ChatGPT hosted remote MCP write | **Plan-gated / not part of baseline acceptance** |
+
+Do not treat the optional hosted tunnel path as a prerequisite for local development.
+
+See [Secure MCP Tunnel Setup](docs/MCP_TUNNEL.md).
+
+---
+
+## Project-Scoped Runtime
+
+Multiple projects can run independently.
+
+```mermaid
+flowchart TB
+    A["Project A"]
+    A --> A_MCP["MCP Service"]
+    A --> A_RUNTIME["Runtime"]
+    A --> A_TUNNEL["Tunnel (optional)"]
+    A --> A_LOGS["Logs"]
+    A --> A_PERM["Permissions"]
+
+    B["Project B"]
+    B --> B_MCP["MCP Service"]
+    B --> B_RUNTIME["Runtime"]
+    B --> B_TUNNEL["Tunnel (optional)"]
+    B --> B_LOGS["Logs"]
+    B --> B_PERM["Permissions"]
+```
+
+Each managed project receives its own service identity derived from its resolved project path.
+
+Example:
+
+```bash
+multiagentos mcp install \
+  --path /absolute/path/to/project1 \
+  --port 8000 \
+  --allow-write
+
+multiagentos mcp install \
+  --path /absolute/path/to/project2 \
+  --port 8001 \
+  --allow-write
+```
+
+Inspect or remove a project-scoped service:
+
+```bash
+multiagentos mcp status --path /absolute/path/to/project1
+multiagentos mcp uninstall --path /absolute/path/to/project1
+```
+
+Supported OS-native lifecycle management includes:
+
+- macOS: per-user `launchd`
+- Windows: per-user Task Scheduler
+
+---
+
+## Cost-Free Development Baseline
+
+The core user-facing path is:
+
+```text
+ChatGPT Free text chat
+        |
+        v
+MultiAgentOS
+        |
+        v
+Local MCP
+        |
+        v
+Project state / source changes / verification
+```
+
+> **Cost-Free policy:** development must be possible without an OpenAI API key by using ChatGPT Free text chat as the AI engine and MultiAgentOS Local MCP as the controlled execution boundary.
+
+This policy does not claim that every ChatGPT feature is unlimited. It defines the intended AI-engine path for ordinary text-based development work.
+
+The baseline is designed around:
+
+```mermaid
+flowchart TB
+    INSTALL["Install MultiAgentOS"]
+    INIT["Initialize project"]
+    MCP["Agent Execution Runtime MCP"]
+    CLIENT["AI Client"]
+
+    INSTALL --> INIT --> MCP --> CLIENT
+
+    CLIENT --> READ["READ"]
+    CLIENT --> PATCH["PATCH"]
+    CLIENT --> TEST["TEST"]
+    CLIENT --> VERIFY["VERIFY"]
+
+    READ --> GH["GitHub"]
+    PATCH --> GH
+    TEST --> GH
+    VERIFY --> GH
+```
+
+“Cost-Free” describes the **MultiAgentOS runtime architecture**. It does not mean that an AI product has unlimited usage or that every optional AI service is free.
+
+Paid AI providers remain optional.
+
+See [Cost-Free Development Baseline](docs/COSTFREE_DEVELOPMENT.md).
+
+---
+
+## Quick Start
+
+### Install
+
+For the Streamable HTTP MCP server:
+
+```bash
+python3 -m pip install "multiagentos[mcp-http]"
+```
+
+No OpenAI API key is required for the local runtime.
+
+### Initialize a project
+
+```mermaid
+flowchart LR
+    INSTALL["Install MultiAgentOS"] --> INIT["multiagentos init ."]
+    INIT --> PROFILE["Project profile"]
+    INIT --> CONFIG[".multiagentos"]
+    INIT --> AGENTS["AGENTS.md"]
+    CONFIG --> MCP["Project MCP"]
+    MCP --> RUNTIME["Agent Execution Runtime"]
+    RUNTIME --> PROJECT["Real project"]
+```
+
+```bash
+cd your-project
+multiagentos init . --component all
+multiagentos status .
+```
+
+See [Project Installation](docs/PROJECT_INSTALLATION.md) for the complete bootstrap contract.
+
+### Run a task
+
+```bash
+multiagentos run \
+  --path . \
+  --objective "run tests" \
+  -- python -m unittest discover -s tests -v
+```
+
+### Start a Chat Agent session
+
+```bash
+multiagentos chat \
+  --path . \
+  --objective "inspect the current project"
+```
+
+### Start local MCP
+
+Read-only:
+
+```bash
+multiagentos mcp serve-http --path .
+```
+
+Read/write:
+
+```bash
+multiagentos mcp serve-http \
+  --path . \
+  --allow-write
+```
+
+The default endpoint is:
+
+```text
+http://127.0.0.1:8000/mcp
+```
+
+### Install as a persistent macOS service
+
+```bash
+multiagentos mcp install --path . --allow-write
+multiagentos mcp status --path .
+```
+
+The service is managed by `launchd` and can survive login/reboot.
+
+---
+
+## Configuration
+
+Project configuration lives under:
+
+```text
+.multiagentos/
+├── components.json
+├── execution.json
+├── chat.json
+├── agents.json
+└── state/
+```
+
+Credentials and provider API keys are not written into project configuration.
+
+---
+
+## Verification
+
+### MultiAgentOS v0.4.3 release verification record
+
+The following results are the recorded verification evidence for the v0.4.3 release:
+
+- **309 tests passed**
+- **3 tests skipped on macOS**
+- macOS managed MCP service verified after reboot/login
+- Project-scoped Secure MCP Tunnel lifecycle verified
+- Tunnel-client control-plane polling verified
+- Python wheel and source distribution build verified
+- Native release artifacts published
+- Local Agent Execution Runtime filesystem READ / WRITE verified
+- `patch.apply` verified with filesystem readback
+- GitHub-connected development path verified
+
+These bullets are a release verification record, not a claim that the same test count has been freshly executed for every later `main` commit. Current `main` changes are validated by the repository's GitHub Actions workflows.
+
+### Verification boundary
+
+The repository deliberately distinguishes:
+
+```mermaid
+flowchart TB
+    LOCAL["Local Runtime Verification"]
+    LOCAL --> MCP["MCP"]
+    LOCAL --> FS["Filesystem"]
+    LOCAL --> PATCH["Patch"]
+    LOCAL --> PROCESS["Process"]
+    LOCAL --> GH["GitHub"]
+
+    VERIFIED["Verified"]
+    MCP --> VERIFIED
+    FS --> VERIFIED
+    PATCH --> VERIFIED
+    PROCESS --> VERIFIED
+    GH --> VERIFIED
+
+    TUNNEL["Optional Hosted Tunnel"]
+    TUNNEL --> LIFECYCLE["Tunnel lifecycle"]
+    TUNNEL --> POLL["Control-plane polling"]
+    TUNNEL --> REMOTE["Remote client capability"]
+
+    DEP["Environment / plan dependent"]
+    LIFECYCLE --> DEP
+    POLL --> DEP
+    REMOTE --> DEP
+```
+
+This prevents a healthy tunnel from being incorrectly reported as proof of a hosted client-side MCP tool invocation.
+
+---
+
+## Security and Permission Model
+
+MultiAgentOS keeps execution authority behind an explicit runtime boundary.
+
+```mermaid
+flowchart TB
+    INTENT["AI Intent"]
+    REQUEST["MCP Tool Request"]
+    POLICY["Execution Policy"]
+
+    INTENT --> REQUEST --> POLICY
+
+    POLICY --> READ["filesystem.read"]
+    POLICY --> WRITE["filesystem.write"]
+    POLICY --> PATCH["patch.apply"]
+    POLICY --> PROCESS["process / shell"]
+
+    READ --> PROJECT["Real Project"]
+    WRITE --> PROJECT
+    PATCH --> PROJECT
+    PROCESS --> PROJECT
+```
+
+Write and process capabilities require explicit opt-in.
+
+For the tunnel path, keep credentials separated:
+
+```text
+CONTROL_PLANE_TUNNEL_ID
+    → identifies the tunnel
+
+CONTROL_PLANE_API_KEY
+    → runtime credential used by tunnel-client
+
+OPENAI_ADMIN_KEY
+    → tunnel administration only
+```
+
+Do not place an administration key in a long-lived runtime configuration.
+
+---
+
+## Documentation
+
+- [Getting Started](docs/GETTING_STARTED.md)
+- [Project Installation](docs/PROJECT_INSTALLATION.md)
+- [Cost-Free Development Baseline](docs/COSTFREE_DEVELOPMENT.md)
+- [ChatGPT Client Capability Matrix](docs/CHATGPT_CLIENT_CAPABILITIES.md)
+- [Agent Execution Runtime Connection Guide](docs/AGENT_EXECUTION_RUNTIME_CONNECTIONS.md)
+- [Secure MCP Tunnel Setup](docs/MCP_TUNNEL.md)
+- [macOS MCP Service](docs/MACOS_MCP_SERVICE.md)
+- [macOS Tunnel Service](docs/MACOS_TUNNEL_SERVICE.md)
+- [Agent Execution Runtime GitHub Connection](docs/AGENT_EXECUTION_RUNTIME_GITHUB_CONNECTION.md)
+- [Architecture Decisions](docs/ARCHITECTURE_DECISIONS.md)
+- [Agent Plugin Marketplace](docs/PLUGIN_MARKETPLACE.md)
+
+The English README is the canonical technical overview. Localized READMEs should preserve the same architecture, terminology, and cost-free baseline.
+
+**[한국어](README.ko.md)**
+
+---
+
+## License
+
+See [LICENSE](LICENSE).