universal-agent-middleware 0.5.1rc1__tar.gz

universal_agent_middleware-0.5.1rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenJay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

universal_agent_middleware-0.5.1rc1/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE
+include README.md
+include pyproject.toml
+recursive-include tests *.py
+recursive-include tests/fixtures *
+include tests/synthetic_fixtures.py

universal_agent_middleware-0.5.1rc1/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: universal-agent-middleware
+Version: 0.5.1rc1
+Summary: Vendor-neutral local-first middleware for AI agent workspace observation, bounded execution handoff, and evidence review.
+Author: OpenJay
+License: MIT
+Keywords: ai,agents,middleware,interop,mcp,agent-skills,agent-plugins,openapi
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.0.0; extra == "mcp"
+Provides-Extra: service
+Requires-Dist: mcp<3,>=2.0.0; extra == "service"
+Requires-Dist: PyYAML<7,>=6.0; extra == "service"
+Dynamic: license-file
+
+# Universal Agent Middleware (UAM) v0.5.1rc1
+
+**Public Preview RC1** — read-only MCP observation for local codebases
+
+UAM is a vendor-neutral, local-first middleware that lets any reasoning client (ChatGPT, Claude, Cursor, future agents) observe your local project workspaces in real time through a secure read-only interface — with project-level reality coverage, lifecycle tracking, and observation-based diagnostics.
+
+## What it does
+
+```text
+Reasoning client (new session, no history needed)
+       │
+       ▼
+  UAM MCP App (19 read-only tools)
+       │
+       ▼
+  Optional secure MCP tunnel (outbound-only)
+       │
+       ▼
+  Your local machine
+       │
+       ▼
+  Registered workspaces + project reality
+  (my-app, api-service, etc.)
+```
+
+A new conversation can read live repository state — HEAD, branch, files, diffs, search, project reality coverage — without copy-paste and without granting write access.
+
+## Quick start
+
+```bash
+# Install
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[mcp]"
+
+# Register workspaces
+cp config/workspaces.example.json config/workspaces.json
+# Edit workspace roots to match your machine
+
+# Optional: root scope registry for autonomous discovery
+cp examples/root_scopes.example.json config/root_scopes.json
+
+# Local MCP smoke test
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-07-28","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | \
+  uam mcp-sdk-stdio --profile session-read \
+    --registry config/workspaces.json \
+    --state-dir ~/.local/share/uam
+```
+
+For remote clients, configure an outbound MCP tunnel using your platform credentials. See `docs/adapters/MCP.md`.
+
+## Available MCP tools
+
+| Tool | Description |
+|------|-------------|
+| `uam_list_workspaces` | List registered workspaces, capabilities, and project grouping |
+| `uam_workspace_snapshot` | HEAD, branch, head_state, dirty count |
+| `uam_session_bootstrap` | Full reasoning context in one call (project-aware, v2 schema) |
+| `uam_tree` | Directory listing |
+| `uam_read_file` | Read text files (relative paths only) |
+| `uam_search_text` | Search across workspace files |
+| `uam_git_status` | Git HEAD, branch, working tree changes |
+| `uam_git_diff` | Git diff (optionally scoped) |
+| `uam_git_log` | Recent commit history |
+| `uam_verify_audit` | Hash-chain audit log integrity |
+| `uam_project_reality` | Multi-instance project reality snapshot with coverage diagnostics |
+| `uam_list_project_instances` | List workspace instances and discovered worktrees for a project |
+| `uam_list_scopes` | List authorized RootScopes (standing trust zones) |
+| `uam_discover_projects` | Autonomously discover all projects within a scope |
+| `uam_scope_inventory` | Cached project inventory for a scope |
+| `uam_search_scope` | Cross-project text search across entire scope |
+| `uam_explain_coverage` | Per-project coverage gap analysis |
+| `uam_what_am_i_missing` | Aggregate missing reality across active projects |
+| `uam_explore` | Intent-driven exploration with ranking, graph, and retrieval plan |
+
+All session-read tools expose `readOnlyHint=true, destructiveHint=false`. No write, exec, merge, deploy, or credential tools are part of the Public Preview contract.
+
+## Security model
+
+- **Read-only remote surface** — no mutation tools exposed in session-read profile
+- **Path containment** — `.env`, `.git/**`, `../` traversal all denied
+- **Prompt injection defense** — security is middleware-enforced, not model-dependent
+- **No credentials in repo** — tunnel credentials via environment only
+- **Outbound-only tunnel** — no public inbound listener required (optional adapter)
+- **Secret firewall** — credential-like files denied even under broad scope authority
+
+## Architecture
+
+```text
+Reasoning clients / humans
+ChatGPT · Claude · Gemini · Cursor · Copilot · future agents
+                    │
+          northbound adapters
+   HTTP/OpenAPI · MCP (official SDK) · Agent Plugins
+                    │
+                    ▼
+┌────────────────────────────────────────────────┐
+│ Universal Agent Middleware Core                 │
+│ workspace registry → policy → observation      │
+│ project registry → coverage diagnostics        │
+│ audit → execution contract → result review     │
+└──────────────────┬─────────────────────────────┘
+                   │                     │
+             READ ONLY                 .state/
+                   │              contracts/results/audit
+                   ▼
+       registered project workspaces
+       my-app · api-service · others
+```
+
+## Core invariants
+
+- **Vendor-neutral core:** no OpenAI/Anthropic/Cursor/GitHub dependency
+- **Project sovereignty:** target project SSOT remains authoritative
+- **Read-only boundary:** session-read profile grants no write, shell, commit, push, merge, or deploy
+- **Observation ≠ Authority:** UAM reports reality; project governance decides actions
+- **Separate state:** UAM state is physically disjoint from target workspaces
+- **Evidence-bound execution:** (v0.2+ contracts; legacy LocalExecutor is experimental)
+
+## Project reality model (v0.3.1+)
+
+UAM tracks multi-instance projects with orthogonal dimensions:
+
+- **role** — structural function: `canonical-main`, `candidate`, `review-carrier`
+- **lifecycle** — temporal state: `active`, `landed`, `stale`, `superseded`
+- **coverage** — observation completeness per truth surface
+
+Coverage states: `observed`, `externally_verified`, `not_applicable`, `not_observed`, `not_registered`
+
+Project-specific observation profiles in `config/project-observation-profiles/` (local-only, gitignored) define per-project requirements without embedding project semantics into UAM core.
+
+## Documentation
+
+- `docs/REALITY_PREAMBLE.md` — Reality Preamble protocol
+- `docs/BACKLOG.md` — Roadmap and hardening priorities
+- `docs/adapters/MCP.md` — MCP adapter setup
+- `docs/oss/public-profile-contract.md` — Public Preview supported surface
+- `CHANGELOG.md` — Version history
+- `SECURITY.md` — Vulnerability reporting
+- `CONTRIBUTING.md` — Contribution guidelines
+
+## Status
+
+**v0.5.1rc1 — Public Preview RC1**
+
+| Gate | Status |
+|------|--------|
+| Source implementation | PASS (19 read-only MCP tools) |
+| RootScope foundation | PASS |
+| Git repository discovery | PASS |
+| Project grouping | PASS |
+| CoverageGap MVP | PASS |
+| Audit v2 integrity | PASS |
+| Scope search enforcement | PASS (OSS-SEC-001 pre-read boundary) |
+| Portable test suite | PASS (199 tests, 1 skipped; synthetic fixtures) |
+| Python/OS matrix (3.11–3.14) | **PASS** — 8/8 public CI (run `33954828455`) |
+| Public release gates (O0–O9) | **PASS** — live public repo; see `docs/oss/launch-packet.md` |
+| GitHub Release `v0.5.1rc1` | **PASS** — wheel + sdist attached |
+| PyPI distribution | **Configured** — OIDC trusted publishing via `release.yml` (manual Pending Publisher step on pypi.org) |
+
+Public Preview supports SDK stdio session-read profile only. Legacy HTTP adapter and LocalExecutor are experimental and not part of the Preview contract. See `docs/oss/public-profile-contract.md`.
+
+Deferred: forge/runtime observation, write-capable remote tools, autonomous execution, production OAuth.

universal_agent_middleware-0.5.1rc1/README.md

@@ -0,0 +1,162 @@
+# Universal Agent Middleware (UAM) v0.5.1rc1
+
+**Public Preview RC1** — read-only MCP observation for local codebases
+
+UAM is a vendor-neutral, local-first middleware that lets any reasoning client (ChatGPT, Claude, Cursor, future agents) observe your local project workspaces in real time through a secure read-only interface — with project-level reality coverage, lifecycle tracking, and observation-based diagnostics.
+
+## What it does
+
+```text
+Reasoning client (new session, no history needed)
+       │
+       ▼
+  UAM MCP App (19 read-only tools)
+       │
+       ▼
+  Optional secure MCP tunnel (outbound-only)
+       │
+       ▼
+  Your local machine
+       │
+       ▼
+  Registered workspaces + project reality
+  (my-app, api-service, etc.)
+```
+
+A new conversation can read live repository state — HEAD, branch, files, diffs, search, project reality coverage — without copy-paste and without granting write access.
+
+## Quick start
+
+```bash
+# Install
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[mcp]"
+
+# Register workspaces
+cp config/workspaces.example.json config/workspaces.json
+# Edit workspace roots to match your machine
+
+# Optional: root scope registry for autonomous discovery
+cp examples/root_scopes.example.json config/root_scopes.json
+
+# Local MCP smoke test
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-07-28","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | \
+  uam mcp-sdk-stdio --profile session-read \
+    --registry config/workspaces.json \
+    --state-dir ~/.local/share/uam
+```
+
+For remote clients, configure an outbound MCP tunnel using your platform credentials. See `docs/adapters/MCP.md`.
+
+## Available MCP tools
+
+| Tool | Description |
+|------|-------------|
+| `uam_list_workspaces` | List registered workspaces, capabilities, and project grouping |
+| `uam_workspace_snapshot` | HEAD, branch, head_state, dirty count |
+| `uam_session_bootstrap` | Full reasoning context in one call (project-aware, v2 schema) |
+| `uam_tree` | Directory listing |
+| `uam_read_file` | Read text files (relative paths only) |
+| `uam_search_text` | Search across workspace files |
+| `uam_git_status` | Git HEAD, branch, working tree changes |
+| `uam_git_diff` | Git diff (optionally scoped) |
+| `uam_git_log` | Recent commit history |
+| `uam_verify_audit` | Hash-chain audit log integrity |
+| `uam_project_reality` | Multi-instance project reality snapshot with coverage diagnostics |
+| `uam_list_project_instances` | List workspace instances and discovered worktrees for a project |
+| `uam_list_scopes` | List authorized RootScopes (standing trust zones) |
+| `uam_discover_projects` | Autonomously discover all projects within a scope |
+| `uam_scope_inventory` | Cached project inventory for a scope |
+| `uam_search_scope` | Cross-project text search across entire scope |
+| `uam_explain_coverage` | Per-project coverage gap analysis |
+| `uam_what_am_i_missing` | Aggregate missing reality across active projects |
+| `uam_explore` | Intent-driven exploration with ranking, graph, and retrieval plan |
+
+All session-read tools expose `readOnlyHint=true, destructiveHint=false`. No write, exec, merge, deploy, or credential tools are part of the Public Preview contract.
+
+## Security model
+
+- **Read-only remote surface** — no mutation tools exposed in session-read profile
+- **Path containment** — `.env`, `.git/**`, `../` traversal all denied
+- **Prompt injection defense** — security is middleware-enforced, not model-dependent
+- **No credentials in repo** — tunnel credentials via environment only
+- **Outbound-only tunnel** — no public inbound listener required (optional adapter)
+- **Secret firewall** — credential-like files denied even under broad scope authority
+
+## Architecture
+
+```text
+Reasoning clients / humans
+ChatGPT · Claude · Gemini · Cursor · Copilot · future agents
+                    │
+          northbound adapters
+   HTTP/OpenAPI · MCP (official SDK) · Agent Plugins
+                    │
+                    ▼
+┌────────────────────────────────────────────────┐
+│ Universal Agent Middleware Core                 │
+│ workspace registry → policy → observation      │
+│ project registry → coverage diagnostics        │
+│ audit → execution contract → result review     │
+└──────────────────┬─────────────────────────────┘
+                   │                     │
+             READ ONLY                 .state/
+                   │              contracts/results/audit
+                   ▼
+       registered project workspaces
+       my-app · api-service · others
+```
+
+## Core invariants
+
+- **Vendor-neutral core:** no OpenAI/Anthropic/Cursor/GitHub dependency
+- **Project sovereignty:** target project SSOT remains authoritative
+- **Read-only boundary:** session-read profile grants no write, shell, commit, push, merge, or deploy
+- **Observation ≠ Authority:** UAM reports reality; project governance decides actions
+- **Separate state:** UAM state is physically disjoint from target workspaces
+- **Evidence-bound execution:** (v0.2+ contracts; legacy LocalExecutor is experimental)
+
+## Project reality model (v0.3.1+)
+
+UAM tracks multi-instance projects with orthogonal dimensions:
+
+- **role** — structural function: `canonical-main`, `candidate`, `review-carrier`
+- **lifecycle** — temporal state: `active`, `landed`, `stale`, `superseded`
+- **coverage** — observation completeness per truth surface
+
+Coverage states: `observed`, `externally_verified`, `not_applicable`, `not_observed`, `not_registered`
+
+Project-specific observation profiles in `config/project-observation-profiles/` (local-only, gitignored) define per-project requirements without embedding project semantics into UAM core.
+
+## Documentation
+
+- `docs/REALITY_PREAMBLE.md` — Reality Preamble protocol
+- `docs/BACKLOG.md` — Roadmap and hardening priorities
+- `docs/adapters/MCP.md` — MCP adapter setup
+- `docs/oss/public-profile-contract.md` — Public Preview supported surface
+- `CHANGELOG.md` — Version history
+- `SECURITY.md` — Vulnerability reporting
+- `CONTRIBUTING.md` — Contribution guidelines
+
+## Status
+
+**v0.5.1rc1 — Public Preview RC1**
+
+| Gate | Status |
+|------|--------|
+| Source implementation | PASS (19 read-only MCP tools) |
+| RootScope foundation | PASS |
+| Git repository discovery | PASS |
+| Project grouping | PASS |
+| CoverageGap MVP | PASS |
+| Audit v2 integrity | PASS |
+| Scope search enforcement | PASS (OSS-SEC-001 pre-read boundary) |
+| Portable test suite | PASS (199 tests, 1 skipped; synthetic fixtures) |
+| Python/OS matrix (3.11–3.14) | **PASS** — 8/8 public CI (run `33954828455`) |
+| Public release gates (O0–O9) | **PASS** — live public repo; see `docs/oss/launch-packet.md` |
+| GitHub Release `v0.5.1rc1` | **PASS** — wheel + sdist attached |
+| PyPI distribution | **Configured** — OIDC trusted publishing via `release.yml` (manual Pending Publisher step on pypi.org) |
+
+Public Preview supports SDK stdio session-read profile only. Legacy HTTP adapter and LocalExecutor are experimental and not part of the Preview contract. See `docs/oss/public-profile-contract.md`.
+
+Deferred: forge/runtime observation, write-capable remote tools, autonomous execution, production OAuth.

universal_agent_middleware-0.5.1rc1/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "universal-agent-middleware"
+version = "0.5.1rc1"
+description = "Vendor-neutral local-first middleware for AI agent workspace observation, bounded execution handoff, and evidence review."
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [{name = "OpenJay"}]
+keywords = ["ai", "agents", "middleware", "interop", "mcp", "agent-skills", "agent-plugins", "openapi"]
+dependencies = []
+
+[project.optional-dependencies]
+mcp = ["mcp>=2.0.0,<3"]
+service = ["mcp>=2.0.0,<3", "PyYAML>=6.0,<7"]
+
+[project.scripts]
+uam = "universal_agent_middleware.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+universal_agent_middleware = ["tool_contract.json"]

universal_agent_middleware-0.5.1rc1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

universal_agent_middleware-0.5.1rc1/src/universal_agent_middleware/__init__.py

@@ -0,0 +1,3 @@
+"""Universal Agent Middleware."""
+
+__version__ = "0.5.1rc1"

universal_agent_middleware-0.5.1rc1/src/universal_agent_middleware/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Optional client/executor adapters.
+
+Adapters may add vendor- or client-specific metadata, but they must not change
+UAM core capabilities, authority, workspace policy, or contract semantics.
+"""