runlatch 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. runlatch-1.0.0/LICENSE +21 -0
  2. runlatch-1.0.0/PKG-INFO +235 -0
  3. runlatch-1.0.0/README.md +196 -0
  4. runlatch-1.0.0/pyproject.toml +79 -0
  5. runlatch-1.0.0/runlatch/__init__.py +119 -0
  6. runlatch-1.0.0/runlatch/adapters/__init__.py +1 -0
  7. runlatch-1.0.0/runlatch/adapters/executors/__init__.py +13 -0
  8. runlatch-1.0.0/runlatch/adapters/executors/docker_exec.py +184 -0
  9. runlatch-1.0.0/runlatch/adapters/executors/subprocess_exec.py +163 -0
  10. runlatch-1.0.0/runlatch/adapters/llm/__init__.py +16 -0
  11. runlatch-1.0.0/runlatch/adapters/llm/anthropic.py +212 -0
  12. runlatch-1.0.0/runlatch/adapters/llm/gemini.py +213 -0
  13. runlatch-1.0.0/runlatch/adapters/llm/mock.py +62 -0
  14. runlatch-1.0.0/runlatch/adapters/llm/openai_compat.py +244 -0
  15. runlatch-1.0.0/runlatch/adapters/llm/pricing.py +43 -0
  16. runlatch-1.0.0/runlatch/adapters/notifications/__init__.py +23 -0
  17. runlatch-1.0.0/runlatch/adapters/notifications/discord.py +71 -0
  18. runlatch-1.0.0/runlatch/adapters/notifications/email.py +95 -0
  19. runlatch-1.0.0/runlatch/adapters/notifications/github_comment.py +94 -0
  20. runlatch-1.0.0/runlatch/adapters/notifications/router.py +105 -0
  21. runlatch-1.0.0/runlatch/adapters/notifications/slack.py +85 -0
  22. runlatch-1.0.0/runlatch/adapters/notifications/webhook.py +68 -0
  23. runlatch-1.0.0/runlatch/adapters/observability/__init__.py +8 -0
  24. runlatch-1.0.0/runlatch/adapters/observability/otel.py +92 -0
  25. runlatch-1.0.0/runlatch/adapters/storage/__init__.py +27 -0
  26. runlatch-1.0.0/runlatch/adapters/storage/models.py +249 -0
  27. runlatch-1.0.0/runlatch/adapters/storage/sqlalchemy_store.py +659 -0
  28. runlatch-1.0.0/runlatch/config.py +141 -0
  29. runlatch-1.0.0/runlatch/core/__init__.py +80 -0
  30. runlatch-1.0.0/runlatch/core/agent.py +765 -0
  31. runlatch-1.0.0/runlatch/core/events.py +56 -0
  32. runlatch-1.0.0/runlatch/core/exceptions.py +74 -0
  33. runlatch-1.0.0/runlatch/core/policy.py +78 -0
  34. runlatch-1.0.0/runlatch/core/protocols.py +180 -0
  35. runlatch-1.0.0/runlatch/core/redactor.py +129 -0
  36. runlatch-1.0.0/runlatch/core/types.py +336 -0
  37. runlatch-1.0.0/runlatch/core/workflow.py +451 -0
  38. runlatch-1.0.0/runlatch/runtime/__init__.py +1 -0
  39. runlatch-1.0.0/runlatch/runtime/cli/__init__.py +1 -0
  40. runlatch-1.0.0/runlatch/runtime/cli/main.py +720 -0
  41. runlatch-1.0.0/runlatch/runtime/server/__init__.py +5 -0
  42. runlatch-1.0.0/runlatch/runtime/server/app.py +76 -0
  43. runlatch-1.0.0/runlatch/runtime/server/auth.py +89 -0
  44. runlatch-1.0.0/runlatch/runtime/server/deps.py +148 -0
  45. runlatch-1.0.0/runlatch/runtime/server/routes/__init__.py +1 -0
  46. runlatch-1.0.0/runlatch/runtime/server/routes/approvals.py +144 -0
  47. runlatch-1.0.0/runlatch/runtime/server/routes/health.py +39 -0
  48. runlatch-1.0.0/runlatch/runtime/server/routes/metrics.py +19 -0
  49. runlatch-1.0.0/runlatch/runtime/server/routes/runs.py +294 -0
  50. runlatch-1.0.0/runlatch/runtime/server/routes/ui.py +88 -0
  51. runlatch-1.0.0/runlatch/runtime/server/routes/webhooks.py +139 -0
  52. runlatch-1.0.0/runlatch/runtime/workers/__init__.py +23 -0
  53. runlatch-1.0.0/runlatch/runtime/workers/agent_tasks.py +391 -0
  54. runlatch-1.0.0/runlatch/runtime/workers/celery_app.py +140 -0
  55. runlatch-1.0.0/runlatch/runtime/workers/maintenance_tasks.py +80 -0
  56. runlatch-1.0.0/runlatch/runtime/workers/notification_tasks.py +192 -0
  57. runlatch-1.0.0/runlatch/toolkits/__init__.py +26 -0
  58. runlatch-1.0.0/runlatch/toolkits/filesystem.py +191 -0
  59. runlatch-1.0.0/runlatch/toolkits/git.py +112 -0
  60. runlatch-1.0.0/runlatch/toolkits/github.py +184 -0
  61. runlatch-1.0.0/runlatch/toolkits/mcp.py +362 -0
  62. runlatch-1.0.0/runlatch/toolkits/shell.py +52 -0
  63. runlatch-1.0.0/runlatch/tools/__init__.py +5 -0
  64. runlatch-1.0.0/runlatch/tools/git_patcher.py +155 -0
  65. runlatch-1.0.0/runlatch/tools/registry.py +199 -0
  66. runlatch-1.0.0/runlatch/tools/sandbox.py +92 -0
  67. runlatch-1.0.0/runlatch/workflows/__init__.py +35 -0
  68. runlatch-1.0.0/runlatch/workflows/ci_triage.py +160 -0
  69. runlatch-1.0.0/runlatch/workflows/dep_audit.py +154 -0
  70. runlatch-1.0.0/runlatch/workflows/doc_sync.py +187 -0
  71. runlatch-1.0.0/runlatch/workflows/issue_to_pr.py +185 -0
  72. runlatch-1.0.0/runlatch/workflows/pr_review.py +168 -0
  73. runlatch-1.0.0/runlatch.egg-info/PKG-INFO +235 -0
  74. runlatch-1.0.0/runlatch.egg-info/SOURCES.txt +77 -0
  75. runlatch-1.0.0/runlatch.egg-info/dependency_links.txt +1 -0
  76. runlatch-1.0.0/runlatch.egg-info/entry_points.txt +2 -0
  77. runlatch-1.0.0/runlatch.egg-info/requires.txt +32 -0
  78. runlatch-1.0.0/runlatch.egg-info/top_level.txt +1 -0
  79. runlatch-1.0.0/setup.cfg +4 -0
runlatch-1.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Prathamesh Ghatkar
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,235 @@
1
+ Metadata-Version: 2.4
2
+ Name: runlatch
3
+ Version: 1.0.0
4
+ Summary: Durable, HITL-First Execution Runtime for Autonomous Developer Agents
5
+ Author-email: Prathamesh Ghatkar <prathameshghatkar54@gmail.com>
6
+ License: MIT
7
+ Requires-Python: >=3.11
8
+ Description-Content-Type: text/markdown
9
+ License-File: LICENSE
10
+ Requires-Dist: pydantic<3.0,>=2.6
11
+ Requires-Dist: pydantic-settings<3.0,>=2.2
12
+ Requires-Dist: httpx<1.0,>=0.27
13
+ Requires-Dist: sqlalchemy[asyncio]<3.0,>=2.0
14
+ Requires-Dist: aiosqlite<1.0,>=0.20
15
+ Requires-Dist: typer<1.0,>=0.12
16
+ Requires-Dist: rich<16.0,>=13.7
17
+ Provides-Extra: mcp
18
+ Requires-Dist: mcp<2.0,>=1.2; extra == "mcp"
19
+ Provides-Extra: server
20
+ Requires-Dist: fastapi<1.0,>=0.115; extra == "server"
21
+ Requires-Dist: uvicorn[standard]<1.0,>=0.30; extra == "server"
22
+ Requires-Dist: jinja2<4.0,>=3.1; extra == "server"
23
+ Requires-Dist: asyncpg<1.0,>=0.29; extra == "server"
24
+ Requires-Dist: alembic<2.0,>=1.13; extra == "server"
25
+ Requires-Dist: celery[redis]<6.0,>=5.4; extra == "server"
26
+ Requires-Dist: redis<6.0,>=5.0; extra == "server"
27
+ Requires-Dist: structlog<25.0,>=24.1; extra == "server"
28
+ Provides-Extra: observability
29
+ Requires-Dist: opentelemetry-api>=1.26; extra == "observability"
30
+ Requires-Dist: opentelemetry-sdk>=1.26; extra == "observability"
31
+ Requires-Dist: opentelemetry-exporter-otlp>=1.26; extra == "observability"
32
+ Provides-Extra: dev
33
+ Requires-Dist: pytest>=8.0; extra == "dev"
34
+ Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
35
+ Requires-Dist: respx>=0.21; extra == "dev"
36
+ Requires-Dist: ruff>=0.6; extra == "dev"
37
+ Requires-Dist: mypy>=1.11; extra == "dev"
38
+ Dynamic: license-file
39
+
40
+ # `runlatch` — Durable, HITL-First Execution Runtime for Autonomous Developer Agents
41
+
42
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
43
+ [![Python: 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB.svg)](pyproject.toml)
44
+ [![Architecture: Hexagonal](https://img.shields.io/badge/Architecture-Hexagonal-10b981.svg)](AGENTS.md)
45
+ [![MCP: Governed](https://img.shields.io/badge/MCP-Fail--Closed_Governance-8b5cf6.svg)](runlatch/toolkits/mcp.py)
46
+
47
+ > *The MCP-native, event-driven Python runtime for autonomous developer workflows — zero-infra locally on SQLite, production-hardened with stateless pause/resume approvals on FastAPI, PostgreSQL, Redis, and Celery.*
48
+
49
+ ---
50
+
51
+ ## Why `runlatch`?
52
+
53
+ Existing Python agent tools force an awkward choice:
54
+ - **In-process SDKs** (PydanticAI, OpenAI Agents SDK) give clean tool calling, *but* stop at `await agent.run()` — no durable background workers, no pause/resume human approvals across process restarts, no webhook idempotency, and no multi-channel notifications.
55
+ - **Conversational frameworks** (CrewAI, AutoGen, LangGraph) bring heavy dependency trees and non-deterministic chat loops without native git worktree isolation or fail-closed tool risk tiers.
56
+
57
+ **`runlatch` provides the missing execution & governance runtime in a two-gear architecture:**
58
+
59
+ 1. **Gear 1 — Zero-Infra Local SDK & CLI (`pip install runlatch`)**:
60
+ - Define typed tools with `@tool` or wrap any **Model Context Protocol (MCP)** server with `MCPToolkit`.
61
+ - Enforce deterministic `RiskTier` policies (`READ`, `WRITE`, `EXEC`, `EXTERNAL`), automatic secret redaction, duplicate tool-call loop detection, and hard token/USD budget caps.
62
+ - Persist durable checkpoints locally via async SQLAlchemy 2.0 + `aiosqlite` — zero Docker or Redis required.
63
+ 2. **Gear 2 — Distributed Production Runtime (`pip install "runlatch[server]"`)**:
64
+ - Run the **exact same Python workflows** behind **FastAPI**, **PostgreSQL**, **Redis + Celery** (3 isolated queues + Beat scheduler), a **Zero-Build Jinja2/HTMX Live Run Inspector (`/ui`)**, and a **5-Channel Notification Engine** (Slack Block Kit, Discord, GitHub PR comments, HMAC-signed Webhooks, SMTP Email).
65
+ 3. **Stateless Human-in-the-Loop (HITL) Git Worktree Pause & Resume**:
66
+ - When an agent calls an `EXTERNAL` tool (`git_push`, `github_create_pr`), `runlatch` captures both modified and brand-new untracked files (`git add -N .` + `git diff HEAD`, excluding binaries, capped at `512 KB`), saves `workspace_patch` + `workspace_meta` to the DB, frees the worker slot immediately, and dispatches a signed link to a **read-only confirmation page** (`GET /ui/approvals/{id}?sig=...&exp=...` — immune to Slack/email link-unfurler `GET` prefetches).
67
+ - Once a human clicks **Approve** (`POST /api/v1/approvals/{id}/decision` guarded by `SELECT ... FOR UPDATE`), *any* healthy worker clones/fetches `base_commit_sha` into a fresh `git worktree`, applies the patch via `git apply --3way`, and completes the run.
68
+
69
+ ---
70
+
71
+ ## System Architecture
72
+
73
+ ```mermaid
74
+ flowchart TB
75
+ subgraph Triggers["Triggers & Clients"]
76
+ CLI["CLI (`runlatch`) / Python SDK"]
77
+ GH["GitHub Webhooks (PR, Issue, CI, Push)"]
78
+ CRON["Celery Beat (5m Approval Sweeper + Weekly Audit)"]
79
+ end
80
+
81
+ subgraph ControlPlane["FastAPI Control Plane + HTMX UI (Layer 2)"]
82
+ API["REST + SSE API & Bearer Auth"]
83
+ UI["HTMX Run Inspector (`/ui`) & Read-Only Approval Page (`/ui/approvals/{id}`)"]
84
+ WH["Webhook Verifier (HMAC-SHA256 + Redis `SET NX EX 86400`)"]
85
+ end
86
+
87
+ subgraph Queue["Redis + Celery 3-Queue Backbone"]
88
+ Q_RUNS["Queue: `agent.runs` (`NullPool` Async Runner)"]
89
+ Q_NOTIFY["Queue: `agent.notifications` (5x Exponential Backoff)"]
90
+ Q_MAINT["Queue: `agent.maintenance`"]
91
+ end
92
+
93
+ subgraph Core["Hexagonal Core & Toolkits (Layer 1 — Zero External Framework Imports)"]
94
+ WF["Multi-Step `Workflow` & `StepExecutor` Protocol"]
95
+ AGENT["Bounded ReAct `Agent` + Loop Detector + Budget Caps"]
96
+ POLICY["`PolicyEngine` (`READ` / `WRITE` / `EXEC` / `EXTERNAL`) + `SecretRedactor`"]
97
+ TK["`FileToolkit` (`SEARCH/REPLACE`) · `GitToolkit` (`worktree`) · `ShellToolkit` · `GitHubToolkit` · `MCPToolkit`"]
98
+ LLM["LLM Adapters (OpenAI/Ollama/Groq/GitHub Models · Anthropic · Gemini · Mock)"]
99
+ end
100
+
101
+ subgraph Storage["Unified Async Storage & Notifications"]
102
+ DB[("SQLite (`aiosqlite`) Locally\nPostgreSQL (`asyncpg`) in Prod")]
103
+ NOTIF["NotificationRouter (Slack · Discord · GitHub · Webhook · SMTP Email)"]
104
+ end
105
+
106
+ CLI --> WF
107
+ GH --> WH --> Q_RUNS
108
+ CRON --> Q_MAINT
109
+ API --> Q_RUNS
110
+ UI -- "POST /api/v1/approvals/{id}/decision" --> API
111
+
112
+ Q_RUNS --> WF --> AGENT
113
+ AGENT <--> POLICY
114
+ AGENT <--> LLM
115
+ AGENT <--> TK
116
+ AGENT <--> DB
117
+ Q_RUNS -- "Approval Requested / Run Completed" --> Q_NOTIFY --> NOTIF --> DB
118
+ ```
119
+
120
+ ---
121
+
122
+ ## Quickstart (60 Seconds, `$0.00` API Spend)
123
+
124
+ ### 1. Install & Run Built-in Flagship Workflows in `--demo` Mode
125
+
126
+ ```bash
127
+ pip install -e ".[dev]"
128
+
129
+ # Initialize runlatch.toml policy config
130
+ runlatch init
131
+
132
+ # Run autonomous PR review at $0.00 using deterministic multi-turn traces + real local git/file tools
133
+ runlatch run pr-review --demo
134
+
135
+ # Run all 5 flagship workflows in --demo mode
136
+ runlatch run ci-triage --demo
137
+ runlatch run dep-audit --demo
138
+ runlatch run issue-to-pr --demo # Pauses at HITL gate -> approve with `runlatch approve <id>`
139
+ runlatch run doc-sync --demo # Pauses at HITL gate -> approve with `runlatch approve <id>`
140
+ ```
141
+
142
+ See a full recorded terminal trace in [`examples/traces/pr_review_demo.md`](examples/traces/pr_review_demo.md).
143
+
144
+ ### 2. Minimal 15-Line Python Agent (Local Ollama / Groq / GitHub Models / OpenAI / Anthropic / Gemini)
145
+
146
+ ```python
147
+ import asyncio
148
+ from runlatch import Agent, FileToolkit, GitToolkit, OpenAICompatibleProvider
149
+
150
+ async def main() -> None:
151
+ agent = Agent(
152
+ name="git-summarizer",
153
+ # Zero-cost presets: .ollama(), .groq(), .github_models() — or AnthropicProvider / GeminiProvider
154
+ provider=OpenAICompatibleProvider.ollama(model="qwen2.5-coder:7b"),
155
+ tools=[*GitToolkit(".").tools(), *FileToolkit(".").tools()],
156
+ max_cost_usd=0.05,
157
+ )
158
+ result = await agent.run("Inspect my git status and summarize the repository files.")
159
+ print(result.output)
160
+ print(f"Tokens: {result.total_tokens} | Cost: ${result.total_cost_usd:.4f}")
161
+
162
+ asyncio.run(main())
163
+ ```
164
+
165
+ ### 3. Fail-Closed MCP Server Governance (`MCPToolkit`)
166
+
167
+ Wrap any third-party MCP server (`stdio` or `streamable_http`) with deterministic risk tiers, glob overrides, secret redaction, and HITL pause/resume — without trusting remote `readOnlyHint` annotations:
168
+
169
+ ```python
170
+ from runlatch import MCPServerConfig, MCPToolkit, PolicyEngine, RiskTier
171
+
172
+ config = MCPServerConfig(server_name="ops", transport="stdio", command="npx", args=["-y", "@modelcontextprotocol/server-postgres"])
173
+
174
+ async with MCPToolkit(
175
+ config,
176
+ # Fail-closed: all discovered tools default to RiskTier.EXTERNAL (requires approval).
177
+ # Exact match wins over fnmatch glob; remote readOnlyHint is never trusted blindly.
178
+ tool_risk_overrides={
179
+ "ops__get_*": RiskTier.READ,
180
+ "ops__get_secret_dump": RiskTier.EXTERNAL,
181
+ },
182
+ policy=PolicyEngine(auto_approve_max_tier=RiskTier.READ),
183
+ ) as mcp_toolkit:
184
+ tools = await mcp_toolkit.discover_tools()
185
+ ```
186
+
187
+ ---
188
+
189
+ ## Running the Full Production Stack (`FastAPI + HTMX UI + Postgres + Redis + Celery`)
190
+
191
+ ```bash
192
+ cp .env.example .env
193
+ docker compose up --build
194
+ ```
195
+
196
+ - **Live Run Inspector UI (Jinja2 + HTMX):** `http://localhost:8000/ui`
197
+ - **Read-Only HITL Approval Page:** `http://localhost:8000/ui/approvals/{approval_id}?sig=...&exp=...`
198
+ - **Health & Readiness Probes:** `http://localhost:8000/health/live` and `http://localhost:8000/health/ready`
199
+ - **GitHub Webhook Endpoint:** `POST http://localhost:8000/api/v1/webhooks/github`
200
+
201
+ Or start components individually from the CLI:
202
+
203
+ ```bash
204
+ runlatch server --host 0.0.0.0 --port 8000
205
+ runlatch worker --queues agent.runs,agent.maintenance --concurrency 4
206
+ runlatch worker --queues agent.notifications --concurrency 8
207
+ runlatch beat
208
+ ```
209
+
210
+ ---
211
+
212
+ ## Security & Honest Execution Boundaries
213
+
214
+ | Boundary | Deterministic Control in `runlatch` |
215
+ |---|---|
216
+ | **Filesystem Sandbox** | `resolve_safe_path()` enforces `Path.resolve().is_relative_to(workspace_root)`, blocking `..` traversal, symlink escapes, null bytes, and denied globs (`.env*`, `*.pem`, `*.key`, `id_rsa*`, `.git/config`). |
217
+ | **Two-Tier Command Execution** | • **Trusted Local Repos (`SubprocessExecutor`):** `shell=False`, environment stripped to explicit allowlist, shell metacharacters blocked, and raw interpreters (`python`, `bash`, `sh`, `node`, `curl`) strictly forbidden.<br>• **Untrusted External PRs (`DockerSandboxExecutor`):** Runs inside ephemeral containers with `docker run --rm --network=none --cap-drop=ALL --read-only --memory=512m --cpus=1 --security-opt=no-new-privileges`. |
218
+ | **Secret Redaction** | `SecretRedactor` scrubs OpenAI, Anthropic, Groq, GitHub, Slack, AWS, Bearer, PEM private keys, and dynamic runtime secrets (including `SMTP_PASSWORD` and Slack/Discord webhook URLs) from all tool outputs, audit logs, and notifications before persistence or dispatch. |
219
+ | **Safe HITL Approval Links** | Notification links point to a read-only `GET /ui/approvals/{id}` page; state changes happen strictly on `POST /api/v1/approvals/{id}/decision` inside an atomic `SELECT ... FOR UPDATE` transaction. |
220
+
221
+ ---
222
+
223
+ ## Architecture & Engineering Documentation
224
+
225
+ - **[`AGENTS.md`](AGENTS.md)** — Strict hexagonal import boundaries (`tests/unit/test_hexagonal_boundaries.py`) & mandatory engineering invariants.
226
+ - **[`START-HERE-ROADMAP.md`](START-HERE-ROADMAP.md)** — Concentric layer map and vertical slice build guide.
227
+ - **[`product/01-vision-market-differentiation.md`](product/01-vision-market-differentiation.md)** & **[`product/02-use-cases-and-workflows.md`](product/02-use-cases-and-workflows.md)**
228
+ - **[`architecture/03-tech-stack-and-tradeoffs.md`](architecture/03-tech-stack-and-tradeoffs.md)** through **[`architecture/07-security-guardrails-and-observability.md`](architecture/07-security-guardrails-and-observability.md)**
229
+ - **[`engineering/08-repo-structure-and-dx.md`](engineering/08-repo-structure-and-dx.md)** through **[`engineering/10-testing-deployment-and-interview-playbook.md`](engineering/10-testing-deployment-and-interview-playbook.md)**
230
+
231
+ ---
232
+
233
+ ## License
234
+
235
+ Released under the [MIT License](LICENSE).
@@ -0,0 +1,196 @@
1
+ # `runlatch` — Durable, HITL-First Execution Runtime for Autonomous Developer Agents
2
+
3
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
4
+ [![Python: 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB.svg)](pyproject.toml)
5
+ [![Architecture: Hexagonal](https://img.shields.io/badge/Architecture-Hexagonal-10b981.svg)](AGENTS.md)
6
+ [![MCP: Governed](https://img.shields.io/badge/MCP-Fail--Closed_Governance-8b5cf6.svg)](runlatch/toolkits/mcp.py)
7
+
8
+ > *The MCP-native, event-driven Python runtime for autonomous developer workflows — zero-infra locally on SQLite, production-hardened with stateless pause/resume approvals on FastAPI, PostgreSQL, Redis, and Celery.*
9
+
10
+ ---
11
+
12
+ ## Why `runlatch`?
13
+
14
+ Existing Python agent tools force an awkward choice:
15
+ - **In-process SDKs** (PydanticAI, OpenAI Agents SDK) give clean tool calling, *but* stop at `await agent.run()` — no durable background workers, no pause/resume human approvals across process restarts, no webhook idempotency, and no multi-channel notifications.
16
+ - **Conversational frameworks** (CrewAI, AutoGen, LangGraph) bring heavy dependency trees and non-deterministic chat loops without native git worktree isolation or fail-closed tool risk tiers.
17
+
18
+ **`runlatch` provides the missing execution & governance runtime in a two-gear architecture:**
19
+
20
+ 1. **Gear 1 — Zero-Infra Local SDK & CLI (`pip install runlatch`)**:
21
+ - Define typed tools with `@tool` or wrap any **Model Context Protocol (MCP)** server with `MCPToolkit`.
22
+ - Enforce deterministic `RiskTier` policies (`READ`, `WRITE`, `EXEC`, `EXTERNAL`), automatic secret redaction, duplicate tool-call loop detection, and hard token/USD budget caps.
23
+ - Persist durable checkpoints locally via async SQLAlchemy 2.0 + `aiosqlite` — zero Docker or Redis required.
24
+ 2. **Gear 2 — Distributed Production Runtime (`pip install "runlatch[server]"`)**:
25
+ - Run the **exact same Python workflows** behind **FastAPI**, **PostgreSQL**, **Redis + Celery** (3 isolated queues + Beat scheduler), a **Zero-Build Jinja2/HTMX Live Run Inspector (`/ui`)**, and a **5-Channel Notification Engine** (Slack Block Kit, Discord, GitHub PR comments, HMAC-signed Webhooks, SMTP Email).
26
+ 3. **Stateless Human-in-the-Loop (HITL) Git Worktree Pause & Resume**:
27
+ - When an agent calls an `EXTERNAL` tool (`git_push`, `github_create_pr`), `runlatch` captures both modified and brand-new untracked files (`git add -N .` + `git diff HEAD`, excluding binaries, capped at `512 KB`), saves `workspace_patch` + `workspace_meta` to the DB, frees the worker slot immediately, and dispatches a signed link to a **read-only confirmation page** (`GET /ui/approvals/{id}?sig=...&exp=...` — immune to Slack/email link-unfurler `GET` prefetches).
28
+ - Once a human clicks **Approve** (`POST /api/v1/approvals/{id}/decision` guarded by `SELECT ... FOR UPDATE`), *any* healthy worker clones/fetches `base_commit_sha` into a fresh `git worktree`, applies the patch via `git apply --3way`, and completes the run.
29
+
30
+ ---
31
+
32
+ ## System Architecture
33
+
34
+ ```mermaid
35
+ flowchart TB
36
+ subgraph Triggers["Triggers & Clients"]
37
+ CLI["CLI (`runlatch`) / Python SDK"]
38
+ GH["GitHub Webhooks (PR, Issue, CI, Push)"]
39
+ CRON["Celery Beat (5m Approval Sweeper + Weekly Audit)"]
40
+ end
41
+
42
+ subgraph ControlPlane["FastAPI Control Plane + HTMX UI (Layer 2)"]
43
+ API["REST + SSE API & Bearer Auth"]
44
+ UI["HTMX Run Inspector (`/ui`) & Read-Only Approval Page (`/ui/approvals/{id}`)"]
45
+ WH["Webhook Verifier (HMAC-SHA256 + Redis `SET NX EX 86400`)"]
46
+ end
47
+
48
+ subgraph Queue["Redis + Celery 3-Queue Backbone"]
49
+ Q_RUNS["Queue: `agent.runs` (`NullPool` Async Runner)"]
50
+ Q_NOTIFY["Queue: `agent.notifications` (5x Exponential Backoff)"]
51
+ Q_MAINT["Queue: `agent.maintenance`"]
52
+ end
53
+
54
+ subgraph Core["Hexagonal Core & Toolkits (Layer 1 — Zero External Framework Imports)"]
55
+ WF["Multi-Step `Workflow` & `StepExecutor` Protocol"]
56
+ AGENT["Bounded ReAct `Agent` + Loop Detector + Budget Caps"]
57
+ POLICY["`PolicyEngine` (`READ` / `WRITE` / `EXEC` / `EXTERNAL`) + `SecretRedactor`"]
58
+ TK["`FileToolkit` (`SEARCH/REPLACE`) · `GitToolkit` (`worktree`) · `ShellToolkit` · `GitHubToolkit` · `MCPToolkit`"]
59
+ LLM["LLM Adapters (OpenAI/Ollama/Groq/GitHub Models · Anthropic · Gemini · Mock)"]
60
+ end
61
+
62
+ subgraph Storage["Unified Async Storage & Notifications"]
63
+ DB[("SQLite (`aiosqlite`) Locally\nPostgreSQL (`asyncpg`) in Prod")]
64
+ NOTIF["NotificationRouter (Slack · Discord · GitHub · Webhook · SMTP Email)"]
65
+ end
66
+
67
+ CLI --> WF
68
+ GH --> WH --> Q_RUNS
69
+ CRON --> Q_MAINT
70
+ API --> Q_RUNS
71
+ UI -- "POST /api/v1/approvals/{id}/decision" --> API
72
+
73
+ Q_RUNS --> WF --> AGENT
74
+ AGENT <--> POLICY
75
+ AGENT <--> LLM
76
+ AGENT <--> TK
77
+ AGENT <--> DB
78
+ Q_RUNS -- "Approval Requested / Run Completed" --> Q_NOTIFY --> NOTIF --> DB
79
+ ```
80
+
81
+ ---
82
+
83
+ ## Quickstart (60 Seconds, `$0.00` API Spend)
84
+
85
+ ### 1. Install & Run Built-in Flagship Workflows in `--demo` Mode
86
+
87
+ ```bash
88
+ pip install -e ".[dev]"
89
+
90
+ # Initialize runlatch.toml policy config
91
+ runlatch init
92
+
93
+ # Run autonomous PR review at $0.00 using deterministic multi-turn traces + real local git/file tools
94
+ runlatch run pr-review --demo
95
+
96
+ # Run all 5 flagship workflows in --demo mode
97
+ runlatch run ci-triage --demo
98
+ runlatch run dep-audit --demo
99
+ runlatch run issue-to-pr --demo # Pauses at HITL gate -> approve with `runlatch approve <id>`
100
+ runlatch run doc-sync --demo # Pauses at HITL gate -> approve with `runlatch approve <id>`
101
+ ```
102
+
103
+ See a full recorded terminal trace in [`examples/traces/pr_review_demo.md`](examples/traces/pr_review_demo.md).
104
+
105
+ ### 2. Minimal 15-Line Python Agent (Local Ollama / Groq / GitHub Models / OpenAI / Anthropic / Gemini)
106
+
107
+ ```python
108
+ import asyncio
109
+ from runlatch import Agent, FileToolkit, GitToolkit, OpenAICompatibleProvider
110
+
111
+ async def main() -> None:
112
+ agent = Agent(
113
+ name="git-summarizer",
114
+ # Zero-cost presets: .ollama(), .groq(), .github_models() — or AnthropicProvider / GeminiProvider
115
+ provider=OpenAICompatibleProvider.ollama(model="qwen2.5-coder:7b"),
116
+ tools=[*GitToolkit(".").tools(), *FileToolkit(".").tools()],
117
+ max_cost_usd=0.05,
118
+ )
119
+ result = await agent.run("Inspect my git status and summarize the repository files.")
120
+ print(result.output)
121
+ print(f"Tokens: {result.total_tokens} | Cost: ${result.total_cost_usd:.4f}")
122
+
123
+ asyncio.run(main())
124
+ ```
125
+
126
+ ### 3. Fail-Closed MCP Server Governance (`MCPToolkit`)
127
+
128
+ Wrap any third-party MCP server (`stdio` or `streamable_http`) with deterministic risk tiers, glob overrides, secret redaction, and HITL pause/resume — without trusting remote `readOnlyHint` annotations:
129
+
130
+ ```python
131
+ from runlatch import MCPServerConfig, MCPToolkit, PolicyEngine, RiskTier
132
+
133
+ config = MCPServerConfig(server_name="ops", transport="stdio", command="npx", args=["-y", "@modelcontextprotocol/server-postgres"])
134
+
135
+ async with MCPToolkit(
136
+ config,
137
+ # Fail-closed: all discovered tools default to RiskTier.EXTERNAL (requires approval).
138
+ # Exact match wins over fnmatch glob; remote readOnlyHint is never trusted blindly.
139
+ tool_risk_overrides={
140
+ "ops__get_*": RiskTier.READ,
141
+ "ops__get_secret_dump": RiskTier.EXTERNAL,
142
+ },
143
+ policy=PolicyEngine(auto_approve_max_tier=RiskTier.READ),
144
+ ) as mcp_toolkit:
145
+ tools = await mcp_toolkit.discover_tools()
146
+ ```
147
+
148
+ ---
149
+
150
+ ## Running the Full Production Stack (`FastAPI + HTMX UI + Postgres + Redis + Celery`)
151
+
152
+ ```bash
153
+ cp .env.example .env
154
+ docker compose up --build
155
+ ```
156
+
157
+ - **Live Run Inspector UI (Jinja2 + HTMX):** `http://localhost:8000/ui`
158
+ - **Read-Only HITL Approval Page:** `http://localhost:8000/ui/approvals/{approval_id}?sig=...&exp=...`
159
+ - **Health & Readiness Probes:** `http://localhost:8000/health/live` and `http://localhost:8000/health/ready`
160
+ - **GitHub Webhook Endpoint:** `POST http://localhost:8000/api/v1/webhooks/github`
161
+
162
+ Or start components individually from the CLI:
163
+
164
+ ```bash
165
+ runlatch server --host 0.0.0.0 --port 8000
166
+ runlatch worker --queues agent.runs,agent.maintenance --concurrency 4
167
+ runlatch worker --queues agent.notifications --concurrency 8
168
+ runlatch beat
169
+ ```
170
+
171
+ ---
172
+
173
+ ## Security & Honest Execution Boundaries
174
+
175
+ | Boundary | Deterministic Control in `runlatch` |
176
+ |---|---|
177
+ | **Filesystem Sandbox** | `resolve_safe_path()` enforces `Path.resolve().is_relative_to(workspace_root)`, blocking `..` traversal, symlink escapes, null bytes, and denied globs (`.env*`, `*.pem`, `*.key`, `id_rsa*`, `.git/config`). |
178
+ | **Two-Tier Command Execution** | • **Trusted Local Repos (`SubprocessExecutor`):** `shell=False`, environment stripped to explicit allowlist, shell metacharacters blocked, and raw interpreters (`python`, `bash`, `sh`, `node`, `curl`) strictly forbidden.<br>• **Untrusted External PRs (`DockerSandboxExecutor`):** Runs inside ephemeral containers with `docker run --rm --network=none --cap-drop=ALL --read-only --memory=512m --cpus=1 --security-opt=no-new-privileges`. |
179
+ | **Secret Redaction** | `SecretRedactor` scrubs OpenAI, Anthropic, Groq, GitHub, Slack, AWS, Bearer, PEM private keys, and dynamic runtime secrets (including `SMTP_PASSWORD` and Slack/Discord webhook URLs) from all tool outputs, audit logs, and notifications before persistence or dispatch. |
180
+ | **Safe HITL Approval Links** | Notification links point to a read-only `GET /ui/approvals/{id}` page; state changes happen strictly on `POST /api/v1/approvals/{id}/decision` inside an atomic `SELECT ... FOR UPDATE` transaction. |
181
+
182
+ ---
183
+
184
+ ## Architecture & Engineering Documentation
185
+
186
+ - **[`AGENTS.md`](AGENTS.md)** — Strict hexagonal import boundaries (`tests/unit/test_hexagonal_boundaries.py`) & mandatory engineering invariants.
187
+ - **[`START-HERE-ROADMAP.md`](START-HERE-ROADMAP.md)** — Concentric layer map and vertical slice build guide.
188
+ - **[`product/01-vision-market-differentiation.md`](product/01-vision-market-differentiation.md)** & **[`product/02-use-cases-and-workflows.md`](product/02-use-cases-and-workflows.md)**
189
+ - **[`architecture/03-tech-stack-and-tradeoffs.md`](architecture/03-tech-stack-and-tradeoffs.md)** through **[`architecture/07-security-guardrails-and-observability.md`](architecture/07-security-guardrails-and-observability.md)**
190
+ - **[`engineering/08-repo-structure-and-dx.md`](engineering/08-repo-structure-and-dx.md)** through **[`engineering/10-testing-deployment-and-interview-playbook.md`](engineering/10-testing-deployment-and-interview-playbook.md)**
191
+
192
+ ---
193
+
194
+ ## License
195
+
196
+ Released under the [MIT License](LICENSE).
@@ -0,0 +1,79 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "runlatch"
7
+ version = "1.0.0"
8
+ description = "Durable, HITL-First Execution Runtime for Autonomous Developer Agents"
9
+ readme = "README.md"
10
+ license = { text = "MIT" }
11
+ requires-python = ">=3.11"
12
+ authors = [
13
+ { name = "Prathamesh Ghatkar", email = "prathameshghatkar54@gmail.com" },
14
+ ]
15
+ dependencies = [
16
+ "pydantic>=2.6,<3.0",
17
+ "pydantic-settings>=2.2,<3.0",
18
+ "httpx>=0.27,<1.0",
19
+ "sqlalchemy[asyncio]>=2.0,<3.0",
20
+ "aiosqlite>=0.20,<1.0",
21
+ "typer>=0.12,<1.0",
22
+ "rich>=13.7,<16.0",
23
+ ]
24
+
25
+ [project.optional-dependencies]
26
+ mcp = [
27
+ "mcp>=1.2,<2.0",
28
+ ]
29
+ server = [
30
+ "fastapi>=0.115,<1.0",
31
+ "uvicorn[standard]>=0.30,<1.0",
32
+ "jinja2>=3.1,<4.0",
33
+ "asyncpg>=0.29,<1.0",
34
+ "alembic>=1.13,<2.0",
35
+ "celery[redis]>=5.4,<6.0",
36
+ "redis>=5.0,<6.0",
37
+ "structlog>=24.1,<25.0",
38
+ ]
39
+ observability = [
40
+ "opentelemetry-api>=1.26",
41
+ "opentelemetry-sdk>=1.26",
42
+ "opentelemetry-exporter-otlp>=1.26",
43
+ ]
44
+ dev = [
45
+ "pytest>=8.0",
46
+ "pytest-asyncio>=0.23",
47
+ "respx>=0.21",
48
+ "ruff>=0.6",
49
+ "mypy>=1.11",
50
+ ]
51
+
52
+ [project.scripts]
53
+ runlatch = "runlatch.runtime.cli.main:app"
54
+
55
+ [tool.setuptools.packages.find]
56
+ where = ["."]
57
+ include = ["runlatch*"]
58
+
59
+ [tool.ruff]
60
+ line-length = 100
61
+ target-version = "py311"
62
+
63
+ [tool.ruff.lint]
64
+ select = ["E", "F", "I", "UP", "B"]
65
+ ignore = []
66
+
67
+ [tool.mypy]
68
+ python_version = "3.11"
69
+ strict = true
70
+ warn_return_any = true
71
+ warn_unused_configs = true
72
+ disallow_untyped_defs = true
73
+ ignore_missing_imports = true
74
+
75
+ [tool.pytest.ini_options]
76
+ asyncio_mode = "auto"
77
+ testpaths = ["tests"]
78
+ python_files = ["test_*.py"]
79
+ addopts = "-q"
@@ -0,0 +1,119 @@
1
+ """runlatch — Durable, HITL-First Execution Runtime for Autonomous Developer Agents."""
2
+
3
+ from runlatch.adapters.executors import DockerSandboxExecutor, SubprocessExecutor
4
+ from runlatch.adapters.llm import (
5
+ AnthropicProvider,
6
+ GeminiProvider,
7
+ MockLLMProvider,
8
+ OpenAICompatibleProvider,
9
+ )
10
+ from runlatch.adapters.notifications import (
11
+ DiscordNotificationProvider,
12
+ GitHubCommentNotificationProvider,
13
+ NotificationRouter,
14
+ SlackNotificationProvider,
15
+ SMTPEmailNotificationProvider,
16
+ WebhookNotificationProvider,
17
+ )
18
+ from runlatch.adapters.observability import OpenTelemetrySubscriber, RecordedSpan
19
+ from runlatch.adapters.storage import SQLAlchemyCheckpointStore
20
+ from runlatch.config import PolicySettings, RunLatchSettings
21
+ from runlatch.core.agent import Agent
22
+ from runlatch.core.events import EventBus
23
+ from runlatch.core.exceptions import (
24
+ ApprovalAlreadyDecidedError,
25
+ ApprovalExpiredError,
26
+ ApprovalRequiredSignal,
27
+ BudgetExceededError,
28
+ LoopDetectedError,
29
+ PatchTooLargeError,
30
+ PolicyDeniedError,
31
+ RunLatchError,
32
+ SandboxViolationError,
33
+ ToolValidationError,
34
+ )
35
+ from runlatch.core.policy import PolicyEngine
36
+ from runlatch.core.redactor import SecretRedactor
37
+ from runlatch.core.types import (
38
+ BudgetConfig,
39
+ LLMResponse,
40
+ Message,
41
+ NotificationEvent,
42
+ RiskTier,
43
+ RunCheckpoint,
44
+ RunResult,
45
+ RunStatus,
46
+ ToolCall,
47
+ ToolSpec,
48
+ WorkspaceMeta,
49
+ )
50
+ from runlatch.core.workflow import Step, Workflow
51
+ from runlatch.toolkits import (
52
+ FileToolkit,
53
+ GitHubToolkit,
54
+ GitToolkit,
55
+ MCPServerConfig,
56
+ MCPToolDescriptor,
57
+ MCPToolkit,
58
+ ShellToolkit,
59
+ )
60
+ from runlatch.tools.git_patcher import GitWorkspacePatcher
61
+ from runlatch.tools.registry import FunctionTool, ToolRegistry, tool
62
+
63
+ __all__ = [
64
+ "Agent",
65
+ "AnthropicProvider",
66
+ "ApprovalAlreadyDecidedError",
67
+ "ApprovalExpiredError",
68
+ "ApprovalRequiredSignal",
69
+ "BudgetConfig",
70
+ "BudgetExceededError",
71
+ "DiscordNotificationProvider",
72
+ "DockerSandboxExecutor",
73
+ "EventBus",
74
+ "FileToolkit",
75
+ "FunctionTool",
76
+ "GeminiProvider",
77
+ "GitHubCommentNotificationProvider",
78
+ "GitHubToolkit",
79
+ "GitToolkit",
80
+ "GitWorkspacePatcher",
81
+ "LLMResponse",
82
+ "LoopDetectedError",
83
+ "MCPServerConfig",
84
+ "MCPToolDescriptor",
85
+ "MCPToolkit",
86
+ "Message",
87
+ "MockLLMProvider",
88
+ "NotificationEvent",
89
+ "NotificationRouter",
90
+ "OpenAICompatibleProvider",
91
+ "OpenTelemetrySubscriber",
92
+ "PatchTooLargeError",
93
+ "PolicyDeniedError",
94
+ "PolicyEngine",
95
+ "PolicySettings",
96
+ "RecordedSpan",
97
+ "RiskTier",
98
+ "RunCheckpoint",
99
+ "RunLatchError",
100
+ "RunLatchSettings",
101
+ "RunResult",
102
+ "RunStatus",
103
+ "SMTPEmailNotificationProvider",
104
+ "SQLAlchemyCheckpointStore",
105
+ "SandboxViolationError",
106
+ "SecretRedactor",
107
+ "ShellToolkit",
108
+ "SlackNotificationProvider",
109
+ "Step",
110
+ "SubprocessExecutor",
111
+ "ToolCall",
112
+ "ToolRegistry",
113
+ "ToolSpec",
114
+ "ToolValidationError",
115
+ "WebhookNotificationProvider",
116
+ "Workflow",
117
+ "WorkspaceMeta",
118
+ "tool",
119
+ ]
@@ -0,0 +1 @@
1
+ """Adapters layer for runlatch."""
@@ -0,0 +1,13 @@
1
+ """Command executor adapters for runlatch."""
2
+
3
+ from runlatch.adapters.executors.docker_exec import DockerSandboxExecutor
4
+ from runlatch.adapters.executors.subprocess_exec import (
5
+ FORBIDDEN_INTERPRETERS,
6
+ SubprocessExecutor,
7
+ )
8
+
9
+ __all__ = [
10
+ "DockerSandboxExecutor",
11
+ "FORBIDDEN_INTERPRETERS",
12
+ "SubprocessExecutor",
13
+ ]