mad-bros 0.1.0__tar.gz

mad_bros-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+venv/
+__pycache__/
+*.pyc
+*.pyo
+sessions/
+/tmp/mad_*
+.pytest_cache/
+.coverage
+dist/
+build/
+*.egg-info/
+.DS_Store

mad_bros-0.1.0/CHANGELOG.md

@@ -0,0 +1,113 @@
+# CHANGELOG
+
+
+## v0.1.0 (2026-04-15)
+
+### Build System
+
+- **pypi**: Rename package to mad-bros
+  ([`fbb828c`](https://github.com/jlsaco/mad/commit/fbb828cc0e8501fa846725bb1d2d430cecc479e4))
+
+Update PyPI project name from 'mad' to 'mad-bros' across release workflows, documentation, and
+  project configuration. Modify build command to ensure build dependency installation. This rename
+  aligns with the new project identity.
+
+BREAKING CHANGE: Package name change requires users to install 'mad-bros' instead of 'mad'
+
+### Chores
+
+- Add Makefile with common targets
+  ([`73e33d5`](https://github.com/jlsaco/mad/commit/73e33d585ba36dd59e2997cc97a2184d6487570e))
+
+Wraps the day-to-day commands (install, test, serve, clean) behind `make` so operators and future
+  Claude runs have a single entry point. Targets honor HOST=/PORT= overrides for `make serve`.
+  CLAUDE.md and README now point at the Makefile as the source of truth for commands.
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+
+### Continuous Integration
+
+- Implement automated release pipeline with semantic versioning
+  ([`f8eb874`](https://github.com/jlsaco/mad/commit/f8eb87491f1fa80e98f9db9d0f56d31b09a30803))
+
+Add GitHub Actions workflows for CI builds, artifact verification, and automated releases using
+  python-semantic-release. Configure pyproject.toml for packaging, dependencies, and release
+  settings. Include Makefile targets for building and dry-run releases. Add CHANGELOG.md for version
+  tracking and docs/releasing.md for release process documentation. Update .gitignore to exclude
+  venv directories.
+
+### Documentation
+
+- Add initial project documentation and v0.1 specs
+  ([`ee74d08`](https://github.com/jlsaco/mad/commit/ee74d082c04d2aec421a0abcf4c64f77aa726426))
+
+Introduce comprehensive documentation for the Mad project, including an overview in README.md,
+  future improvements in docs/backlog.md, sandbox hardening guide in docs/sandbox-bwrap.md, and a
+  complete spec-driven development package for v0.1 in specs/v0.1/ covering requirements, design,
+  API contract, and implementation plan. This establishes the project's foundation and guides
+  development towards the first functional version.
+
+- **v0.1**: Mandate src/mad/ package layout
+  ([`92d5d17`](https://github.com/jlsaco/mad/commit/92d5d17f8460ec7215d86305105bd7cc14c93d36))
+
+- Rewrite CLAUDE.md hard rule #4 from "Single-file MVP" to a package layout split by concern (api,
+  core, agent, providers) with create_app(store=...) and no module-level globals; update Key files,
+  Commands, and LLMProvider sections accordingly. - Update specs/v0.1 requirements NFR-1, plan rule
+  2, and the design diagram so the spec no longer contradicts the new convention. - Update the 4
+  subagents and /implement command to point at src/mad/ instead of app.py and to enforce the layout
+  in reviews. - Extend README with an Install section (pip install -e .) and a project structure
+  tree.
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+
+### Features
+
+- Initialize project infrastructure for Mad v0.1
+  ([`1494569`](https://github.com/jlsaco/mad/commit/1494569f02344b9b0a923446f765801e37f728ec))
+
+Add core components including Claude agent definitions, slash commands, CI pipeline, FastAPI app
+  skeleton, test fixtures, and security tests. Establish spec-driven development workflow with TDD
+  support, enforcing hard rules for token hygiene, path traversal prevention, and native tool use.
+
+BREAKING CHANGE: Introduces new project structure requiring spec-first development process.
+
+- **api**: Implement session management and provider interfaces
+  ([`b232a75`](https://github.com/jlsaco/mad/commit/b232a756af10e05e32bfd8e635380bdb3f6c2aff))
+
+Introduce core session lifecycle handling including creation, logging, and SSE streaming. Add stub
+  implementations for ClaudeCLIProvider and AnthropicAPIProvider. Expand acceptance tests to cover
+  MVP criteria such as repo cloning, event handling, and session resumption. Enhance security tests
+  with comprehensive path traversal validations and token hygiene checks.
+
+BREAKING CHANGE: Updates session response structure to include workspace and resources_mounted
+  details. Requires client adjustments for new fields.
+
+### Refactoring
+
+- **v0.1**: Migrate app.py into src/mad/ package
+  ([`c652791`](https://github.com/jlsaco/mad/commit/c652791e55f4f333ecaeb597b483eebcb7f65bf8))
+
+Split the monolithic app.py into a pip-installable src/mad/ package: - mad.api: FastAPI app factory
+  (create_app) + routes/sessions.py. No module-level globals; per-process state lives on a
+  SessionStore held in app.state.store so every create_app() call is isolated. - mad.core: log,
+  security (path validation), workspace, resources, sessions (SessionStore). - mad.agent: loop and
+  tools (run_agent_loop takes the store as a parameter). - mad.providers: base (Protocol +
+  ProviderResponse + ToolUse), factory, claude_cli, anthropic_api, fake (FakeScriptedProvider moved
+  out of conftest so tests and production share one implementation). - mad.cli: `mad serve` console
+  entry-point.
+
+pyproject.toml gains build-system (hatchling), [project] metadata and dependencies, a `mad` console
+  script, and pytest pythonpath=["src"]. Tests now import from mad.* and TestClient wraps
+  create_app().
+
+All 35 tests green. No functional changes — this is a pure refactor; FR-7 recovery, FR-10 provider
+  stubs, and the sse-starlette gap are carried over from the previous state as pre-existing debt.
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+
+### Breaking Changes
+
+- **api**: Updates session response structure to include workspace and resources_mounted details.
+  Requires client adjustments for new fields.
+
+- **pypi**: Package name change requires users to install 'mad-bros' instead of 'mad'

mad_bros-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose Salamanca
+
+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.

mad_bros-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: mad-bros
+Version: 0.1.0
+Summary: Multi Agent Develop — self-hosted autonomous Claude sessions against GitHub repos.
+Project-URL: Homepage, https://github.com/jlsaco/mad
+Project-URL: Issues, https://github.com/jlsaco/mad/issues
+Author-email: Jose Salamanca <jose.salamancacoy@gmail.com>, Cristian Moreno <cristianfmoreno95@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Jose Salamanca
+        
+        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.
+License-File: LICENSE
+Keywords: agents,automation,claude,github
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.39
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: uvicorn[standard]>=0.29
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: python-semantic-release>=9.8; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Mad About
+
+> That's mad!
+
+**M**ulti **A**gent **D**evelop — a multi-agent system designed to build software autonomously. It takes an idea and drives it end-to-end: from the first line of code to a working product.
+
+## What is this?
+
+Mad About orchestrates a team of AI agents that collaborate to design, implement, test, and ship software without a human in the loop for every step. You give it a goal; it figures out the rest.
+
+## Status
+
+Early days. The first milestone is **Mad** — a self-hosted API that provisions workspaces, clones repos, and runs Claude agents autonomously against them. See [`specs/v0.1/`](specs/v0.1/README.md) for the full spec-driven package.
+
+## Install
+
+Mad ships as a pip-installable Python package (`mad`). From a checkout:
+
+```bash
+make install   # create venv + editable install with dev deps
+make test      # run the pytest suite
+make serve     # uvicorn factory (override HOST=/PORT= if needed)
+make help      # list every target
+```
+
+All commands are wrapped by the `Makefile`; the raw equivalents live in `pyproject.toml` (the `mad` console script) and in the project documentation.
+
+## Project structure
+
+```
+mad/
+├── pyproject.toml          # package metadata, deps, `mad` console script
+├── src/mad/
+│   ├── api/                # FastAPI app + routes (thin HTTP layer)
+│   │   ├── app.py          # create_app(store=...) factory
+│   │   └── routes/         # sessions, events, stream
+│   ├── core/               # domain — session log, workspace, security, SessionStore
+│   ├── agent/              # harness loop + tool execution
+│   ├── providers/          # LLMProvider protocol + claude_cli / anthropic_api / fake
+│   └── cli.py              # `mad` console entry-point
+├── specs/v0.1/             # spec-driven package for the current milestone
+└── tests/                  # pytest acceptance + security tests
+```
+
+Hard rules and conventions that govern every change live in [`CLAUDE.md`](CLAUDE.md).
+
+## Documentation
+
+- [`specs/v0.1/`](specs/v0.1/README.md) — spec-driven development package for v0.1 (requirements, design, API contract, implementation plan).
+- [`docs/backlog.md`](docs/backlog.md) — known improvements deferred past v0.1.
+- [`docs/sandbox-bwrap.md`](docs/sandbox-bwrap.md) — hardening guide for the execution sandbox using bubblewrap.
+
+## License
+
+See [`LICENSE`](LICENSE).

mad_bros-0.1.0/README.md

@@ -0,0 +1,55 @@
+# Mad About
+
+> That's mad!
+
+**M**ulti **A**gent **D**evelop — a multi-agent system designed to build software autonomously. It takes an idea and drives it end-to-end: from the first line of code to a working product.
+
+## What is this?
+
+Mad About orchestrates a team of AI agents that collaborate to design, implement, test, and ship software without a human in the loop for every step. You give it a goal; it figures out the rest.
+
+## Status
+
+Early days. The first milestone is **Mad** — a self-hosted API that provisions workspaces, clones repos, and runs Claude agents autonomously against them. See [`specs/v0.1/`](specs/v0.1/README.md) for the full spec-driven package.
+
+## Install
+
+Mad ships as a pip-installable Python package (`mad`). From a checkout:
+
+```bash
+make install   # create venv + editable install with dev deps
+make test      # run the pytest suite
+make serve     # uvicorn factory (override HOST=/PORT= if needed)
+make help      # list every target
+```
+
+All commands are wrapped by the `Makefile`; the raw equivalents live in `pyproject.toml` (the `mad` console script) and in the project documentation.
+
+## Project structure
+
+```
+mad/
+├── pyproject.toml          # package metadata, deps, `mad` console script
+├── src/mad/
+│   ├── api/                # FastAPI app + routes (thin HTTP layer)
+│   │   ├── app.py          # create_app(store=...) factory
+│   │   └── routes/         # sessions, events, stream
+│   ├── core/               # domain — session log, workspace, security, SessionStore
+│   ├── agent/              # harness loop + tool execution
+│   ├── providers/          # LLMProvider protocol + claude_cli / anthropic_api / fake
+│   └── cli.py              # `mad` console entry-point
+├── specs/v0.1/             # spec-driven package for the current milestone
+└── tests/                  # pytest acceptance + security tests
+```
+
+Hard rules and conventions that govern every change live in [`CLAUDE.md`](CLAUDE.md).
+
+## Documentation
+
+- [`specs/v0.1/`](specs/v0.1/README.md) — spec-driven development package for v0.1 (requirements, design, API contract, implementation plan).
+- [`docs/backlog.md`](docs/backlog.md) — known improvements deferred past v0.1.
+- [`docs/sandbox-bwrap.md`](docs/sandbox-bwrap.md) — hardening guide for the execution sandbox using bubblewrap.
+
+## License
+
+See [`LICENSE`](LICENSE).

mad_bros-0.1.0/pyproject.toml

@@ -0,0 +1,90 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mad-bros"
+version = "0.1.0"
+description = "Multi Agent Develop — self-hosted autonomous Claude sessions against GitHub repos."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Jose Salamanca", email = "jose.salamancacoy@gmail.com" },
+  { name = "Cristian Moreno", email = "cristianfmoreno95@gmail.com" },
+]
+requires-python = ">=3.11"
+keywords = ["claude", "agents", "automation", "github"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: POSIX :: Linux",
+  "Framework :: FastAPI",
+]
+dependencies = [
+  "fastapi>=0.110",
+  "uvicorn[standard]>=0.29",
+  "anthropic>=0.39",
+  "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "build>=1.2",
+  "twine>=5.1",
+  "python-semantic-release>=9.8",
+]
+
+[project.scripts]
+mad = "mad.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/jlsaco/mad"
+Issues = "https://github.com/jlsaco/mad/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mad"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/mad",
+  "README.md",
+  "LICENSE",
+  "CHANGELOG.md",
+  "pyproject.toml",
+]
+exclude = [
+  "venv",
+  ".venv",
+  "sessions",
+  "tests/fixtures/tmp",
+  "**/__pycache__",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-ra"
+pythonpath = ["src"]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+version_variables = ["src/mad/__init__.py:__version__"]
+branch = "main"
+upload_to_vcs_release = true
+build_command = "python -m pip install build && python -m build"
+commit_message = "chore(release): {version}\n\nCo-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
+commit_parser = "conventional"
+major_on_zero = false
+tag_format = "v{version}"
+
+[tool.semantic_release.changelog]
+changelog_file = "CHANGELOG.md"
+
+[tool.semantic_release.branches.main]
+match = "main"
+prerelease = false

mad_bros-0.1.0/specs/v0.1/README.md

@@ -0,0 +1,21 @@
+# Mad v0.1 — Spec
+
+This folder is the **spec-driven development** package for the first functional version of **Mad**: a self-hosted system that replicates the core of Anthropic Managed Agents on your own hardware.
+
+Mad receives a JSON request that defines an agent and a set of resources (GitHub repositories, inline files), provisions a local workspace, clones the repos, and runs an autonomous session where Claude (via headless CLI or API) works against them.
+
+## How to read this spec
+
+Read the files in order. Each one answers a different question.
+
+| File | Question it answers |
+|---|---|
+| [`requirements.md`](requirements.md) | **What** must be true for v0.1 to be considered done? Functional requirements, constraints, and the MVP acceptance criteria. |
+| [`design.md`](design.md) | **How** does it work internally? Architecture, components, end-to-end request flow. |
+| [`api.md`](api.md) | **What does the outside see?** HTTP contract: endpoints, request/response schemas, headers, events. |
+| [`plan.md`](plan.md) | **How do we build it?** Implementation rules, stack, conventions, out-of-scope items. |
+
+## Related
+
+- [`../../docs/backlog.md`](../../docs/backlog.md) — improvements deliberately deferred past v0.1.
+- [`../../docs/sandbox-bwrap.md`](../../docs/sandbox-bwrap.md) — hardening guide for the execution sandbox.

mad_bros-0.1.0/src/mad/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

mad_bros-0.1.0/src/mad/agent/loop.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from mad.agent.tools import AGENT_TOOLS, execute_tool
+from mad.core import log
+from mad.core.sessions import SessionStore
+from mad.providers import factory
+
+
+async def run_agent_loop(
+    store: SessionStore,
+    session_id: str,
+    session: dict,
+    user_message: str,
+) -> None:
+    """Run the agent loop for one user message.
+
+    Every event is appended to the session log (source of truth — hard rule 6)
+    and pushed to the SSE queue so subscribers see it in real time.
+    """
+    store.emit_and_push(session_id, "session.status_running")
+    session["status"] = "running"
+
+    provider = factory.get_provider(session["agent"]["provider"])
+    system = session["agent"].get("system", "")
+
+    messages: list[dict] = []
+    for event in log.get_events(session_id):
+        if event["type"] == "user.message":
+            messages.append({"role": "user", "content": event["content"]})
+        elif event["type"] == "agent.message" and event.get("content"):
+            messages.append({"role": "assistant", "content": event["content"]})
+
+    if not messages or messages[-1] != {"role": "user", "content": user_message}:
+        messages.append({"role": "user", "content": user_message})
+
+    stop_reason = "end_turn"
+    try:
+        while True:
+            response = await provider.complete(system=system, messages=messages, tools=AGENT_TOOLS)
+            stop_reason = response.stop_reason
+
+            if response.text:
+                store.emit_and_push(session_id, "agent.message", {"content": response.text})
+                messages.append({"role": "assistant", "content": response.text})
+
+            if not response.tool_uses:
+                break
+
+            # Hard rule 1: only structured tool_use blocks are honored.
+            tool_results = []
+            for tu in response.tool_uses:
+                store.emit_and_push(session_id, "agent.tool_use", {
+                    "tool": tu.name,
+                    "input": tu.input,
+                    "tool_use_id": tu.id,
+                })
+                result = execute_tool(session_id, tu)
+                store.emit_and_push(session_id, "agent.tool_result", {
+                    "tool": tu.name,
+                    "result": result,
+                    "tool_use_id": tu.id,
+                })
+                tool_results.append({
+                    "type": "tool_result",
+                    "tool_use_id": tu.id,
+                    "content": result,
+                })
+
+            messages.append({"role": "user", "content": tool_results})
+
+            if stop_reason != "tool_use":
+                break
+
+    except Exception as exc:
+        store.emit_and_push(session_id, "session.error", {"error": str(exc)})
+        stop_reason = "error"
+
+    store.emit_and_push(session_id, "session.status_idle", {"stop_reason": stop_reason})
+    session["status"] = "idle"
+
+    q = store.sse_queues.get(session_id)
+    if q is not None:
+        await q.put(None)

mad_bros-0.1.0/src/mad/agent/tools.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import subprocess
+
+from mad.core.workspace import workspace_path
+from mad.providers.base import ToolUse
+
+AGENT_TOOLS = [
+    {
+        "name": "bash",
+        "description": "Execute a bash command in the workspace sandbox.",
+        "input_schema": {
+            "type": "object",
+            "properties": {"command": {"type": "string"}},
+            "required": ["command"],
+        },
+    },
+    {
+        "name": "read_file",
+        "description": "Read a file from the workspace.",
+        "input_schema": {
+            "type": "object",
+            "properties": {"path": {"type": "string"}},
+            "required": ["path"],
+        },
+    },
+    {
+        "name": "write_file",
+        "description": "Write content to a file in the workspace.",
+        "input_schema": {
+            "type": "object",
+            "properties": {"path": {"type": "string"}, "content": {"type": "string"}},
+            "required": ["path", "content"],
+        },
+    },
+]
+
+
+def execute_tool(session_id: str, tool_use: ToolUse) -> str:
+    """Execute a structured tool call in the session workspace."""
+    workspace = workspace_path(session_id)
+    if tool_use.name == "bash":
+        command = tool_use.input.get("command", "")
+        result = subprocess.run(
+            command, shell=True, cwd=str(workspace),
+            capture_output=True, text=True, timeout=60,
+        )
+        return result.stdout + (("\n" + result.stderr) if result.stderr else "")
+    if tool_use.name == "read_file":
+        path = workspace / tool_use.input.get("path", "").lstrip("/")
+        try:
+            return path.read_text()
+        except Exception as exc:
+            return f"error: {exc}"
+    if tool_use.name == "write_file":
+        path = workspace / tool_use.input.get("path", "").lstrip("/")
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(tool_use.input.get("content", ""))
+        return "ok"
+    return f"unknown tool: {tool_use.name}"

mad_bros-0.1.0/src/mad/api/__init__.py

@@ -0,0 +1,3 @@
+from mad.api.app import create_app
+
+__all__ = ["create_app"]

mad_bros-0.1.0/src/mad/api/app.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from mad.api.routes.sessions import router as sessions_router
+from mad.core import log
+from mad.core.sessions import SessionStore
+
+
+def create_app(store: SessionStore | None = None) -> FastAPI:
+    """Build a FastAPI app with an injected SessionStore.
+
+    Every call creates an isolated instance — tests get a fresh store
+    so state never leaks across cases.
+    """
+    app = FastAPI(title="Mad", version="0.1.0")
+    app.state.store = store or SessionStore()
+
+    @app.on_event("startup")
+    async def _startup() -> None:
+        log.ensure_sessions_dir()
+
+    app.include_router(sessions_router)
+    return app

mad_bros-0.1.0/src/mad/api/routes/sessions.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import shutil
+import uuid
+from pathlib import Path
+
+from fastapi import APIRouter, Header, HTTPException, Request
+from fastapi.responses import StreamingResponse
+
+from mad.agent.loop import run_agent_loop
+from mad.core import log
+from mad.core.resources import provision_file, provision_github_repo
+from mad.core.security import validate_mount_path
+from mad.core.sessions import SessionStore
+from mad.core.workspace import workspace_path
+
+router = APIRouter()
+
+
+def _store(request: Request) -> SessionStore:
+    return request.app.state.store
+
+
+@router.post("/v1/sessions")
+async def create_session(
+    request: Request,
+    idempotency_key: str | None = Header(default=None, alias="Idempotency-Key"),
+) -> dict:
+    log.ensure_sessions_dir()
+    store = _store(request)
+
+    if idempotency_key and idempotency_key in store.idempotency:
+        existing_id = store.idempotency[idempotency_key]
+        return store.sessions[existing_id]["response"]
+
+    body = await request.json()
+    agent = body["agent"]
+    resources = body.get("resources", [])
+
+    for res in resources:
+        validate_mount_path(res["mount_path"])
+
+    session_id = "sesn_" + uuid.uuid4().hex[:12]
+    workspace = workspace_path(session_id)
+    workspace.mkdir(parents=True, exist_ok=True)
+
+    log.emit(session_id, "session.created", {"agent": agent["name"]})
+
+    resources_mounted = []
+    for res in resources:
+        if res["type"] == "github_repository":
+            mounted = provision_github_repo(session_id, res)
+        elif res["type"] == "file":
+            mounted = provision_file(session_id, res)
+        else:
+            raise HTTPException(status_code=400, detail=f"Unknown resource type: {res['type']!r}")
+        resources_mounted.append(mounted)
+
+    response = {
+        "session_id": session_id,
+        "status": "created",
+        "workspace": str(workspace),
+        "resources_mounted": resources_mounted,
+    }
+
+    store.sessions[session_id] = {
+        "session_id": session_id,
+        "agent": agent,
+        "workspace": str(workspace),
+        "status": "created",
+        "response": response,
+    }
+    store.get_or_create_queue(session_id)
+
+    if idempotency_key:
+        store.idempotency[idempotency_key] = session_id
+
+    return response
+
+
+@router.post("/v1/sessions/{session_id}/events")
+async def send_events(session_id: str, request: Request) -> dict:
+    store = _store(request)
+    if session_id not in store.sessions:
+        raise HTTPException(status_code=404, detail="Session not found")
+
+    body = await request.json()
+    events = body.get("events", [])
+    session = store.sessions[session_id]
+
+    for event in events:
+        event_type = event.get("type")
+        if event_type == "user.message":
+            content = event.get("content", "")
+            log.emit(session_id, "user.message", {"content": content})
+            asyncio.create_task(run_agent_loop(store, session_id, session, content))
+
+    return {"status": "accepted"}
+
+
+@router.get("/v1/sessions/{session_id}/stream")
+async def stream_session(session_id: str, request: Request) -> StreamingResponse:
+    store = _store(request)
+    if session_id not in store.sessions:
+        raise HTTPException(status_code=404, detail="Session not found")
+
+    queue = store.get_or_create_queue(session_id)
+
+    async def event_generator():
+        while True:
+            event = await queue.get()
+            if event is None:
+                break
+            yield f"data: {json.dumps(event)}\n\n"
+
+    return StreamingResponse(event_generator(), media_type="text/event-stream")
+
+
+@router.get("/v1/sessions/{session_id}")
+async def get_session(session_id: str, request: Request) -> dict:
+    store = _store(request)
+    if session_id not in store.sessions:
+        raise HTTPException(status_code=404, detail="Session not found")
+    session = store.sessions[session_id]
+    events = log.get_events(session_id)
+    return {
+        "session_id": session_id,
+        "status": session["status"],
+        "workspace": session["workspace"],
+        "events": events,
+    }
+
+
+@router.get("/v1/sessions")
+async def list_sessions(request: Request) -> list:
+    store = _store(request)
+    return [
+        {"session_id": sid, "status": s["status"]}
+        for sid, s in store.sessions.items()
+    ]
+
+
+@router.delete("/v1/sessions/{session_id}")
+async def delete_session(session_id: str, request: Request) -> dict:
+    store = _store(request)
+    if session_id not in store.sessions:
+        raise HTTPException(status_code=404, detail="Session not found")
+
+    session = store.sessions[session_id]
+    workspace = Path(session["workspace"])
+
+    if workspace.exists():
+        shutil.rmtree(workspace)
+
+    session["status"] = "deleted"
+    store.sse_queues.pop(session_id, None)
+
+    return {"status": "deleted", "session_id": session_id}

mad_bros-0.1.0/src/mad/cli.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import sys
+
+
+def main() -> None:
+    argv = sys.argv[1:]
+    if not argv or argv[0] in {"-h", "--help"}:
+        print("usage: mad serve [--host HOST] [--port PORT]")
+        return
+    if argv[0] == "serve":
+        import uvicorn
+
+        host = "0.0.0.0"
+        port = 8000
+        it = iter(argv[1:])
+        for token in it:
+            if token == "--host":
+                host = next(it)
+            elif token == "--port":
+                port = int(next(it))
+        uvicorn.run("mad.api.app:create_app", host=host, port=port, factory=True)
+        return
+    print(f"unknown command: {argv[0]!r}", file=sys.stderr)
+    sys.exit(2)

mad_bros-0.1.0/src/mad/core/log.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+SESSIONS_DIR = Path("sessions")
+
+
+def ensure_sessions_dir() -> None:
+    SESSIONS_DIR.mkdir(exist_ok=True)
+
+
+def log_path(session_id: str) -> Path:
+    return SESSIONS_DIR / f"{session_id}.jsonl"
+
+
+def emit(session_id: str, event_type: str, data: dict[str, Any] | None = None) -> dict:
+    """Print an event to stdout AND append it to the session JSONL log.
+
+    The log is the source of truth (CLAUDE.md hard rule 6).
+    """
+    event = {"type": event_type, "timestamp": datetime.now(timezone.utc).isoformat()}
+    if data:
+        event.update(data)
+    line = json.dumps(event)
+    print(line)
+    ensure_sessions_dir()
+    with log_path(session_id).open("a") as f:
+        f.write(line + "\n")
+    return event
+
+
+def get_events(session_id: str) -> list[dict]:
+    p = log_path(session_id)
+    if not p.exists():
+        return []
+    events: list[dict] = []
+    for ln in p.read_text().splitlines():
+        ln = ln.strip()
+        if ln:
+            events.append(json.loads(ln))
+    return events

mad_bros-0.1.0/src/mad/core/resources.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+from mad.core.workspace import local_path_for_mount
+
+
+def provision_github_repo(session_id: str, resource: dict) -> dict:
+    url: str = resource["url"]
+    mount_path: str = resource["mount_path"]
+    token: str | None = resource.get("authorization_token")
+    checkout: dict | None = resource.get("checkout")
+
+    local_path = local_path_for_mount(session_id, mount_path)
+    local_path.mkdir(parents=True, exist_ok=True)
+
+    clone_url = url
+    if token and url.startswith("https://"):
+        clone_url = url.replace("https://", f"https://{token}@", 1)
+
+    cmd = ["git", "clone", "-q", clone_url, str(local_path)]
+    if checkout and checkout.get("type") == "branch":
+        cmd = ["git", "clone", "-q", "-b", checkout["name"], clone_url, str(local_path)]
+
+    shutil.rmtree(local_path)
+    subprocess.run(cmd, check=True, capture_output=True)
+
+    # Strip token from remote after clone (CLAUDE.md hard rule 2)
+    subprocess.run(
+        ["git", "-C", str(local_path), "remote", "set-url", "origin", url],
+        check=True,
+        capture_output=True,
+    )
+
+    return {
+        "type": "github_repository",
+        "url": url,
+        "mount_path": mount_path,
+        "local_path": str(local_path),
+        "status": "cloned",
+    }
+
+
+def provision_file(session_id: str, resource: dict) -> dict:
+    mount_path: str = resource["mount_path"]
+    content: str = resource.get("content", "")
+    local_path = local_path_for_mount(session_id, mount_path)
+    local_path.parent.mkdir(parents=True, exist_ok=True)
+    local_path.write_text(content)
+    return {
+        "type": "file",
+        "mount_path": mount_path,
+        "local_path": str(local_path),
+        "status": "written",
+    }

mad_bros-0.1.0/src/mad/core/security.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+
+from fastapi import HTTPException
+
+WORKSPACE_PREFIX = "/workspace"
+
+
+def validate_mount_path(mount_path: str) -> None:
+    """Reject any mount_path that doesn't resolve inside /workspace.
+
+    Enforces CLAUDE.md hard rule 3 (path traversal prevention).
+    """
+    if not mount_path.startswith("/"):
+        raise HTTPException(status_code=400, detail=f"mount_path {mount_path!r} must be absolute")
+    pure = PurePosixPath(mount_path)
+    stack: list[str] = []
+    for part in pure.parts[1:]:
+        if part == "..":
+            if not stack:
+                raise HTTPException(status_code=400, detail=f"mount_path {mount_path!r} escapes workspace")
+            stack.pop()
+        elif part and part != ".":
+            stack.append(part)
+    logical = "/" + "/".join(stack)
+    if not (logical == WORKSPACE_PREFIX or logical.startswith(WORKSPACE_PREFIX + "/")):
+        raise HTTPException(status_code=400, detail=f"mount_path {mount_path!r} escapes workspace")

mad_bros-0.1.0/src/mad/core/sessions.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import asyncio
+
+from mad.core import log
+
+
+class SessionStore:
+    """Holds all per-process session state. Injected into create_app() so
+    tests (and other embeddings) get a fresh instance with no global leakage.
+    """
+
+    def __init__(self) -> None:
+        self.sessions: dict[str, dict] = {}
+        self.idempotency: dict[str, str] = {}
+        self.sse_queues: dict[str, asyncio.Queue] = {}
+
+    def get_or_create_queue(self, session_id: str) -> asyncio.Queue:
+        if session_id not in self.sse_queues:
+            self.sse_queues[session_id] = asyncio.Queue()
+        return self.sse_queues[session_id]
+
+    def push_event(self, session_id: str, event: dict) -> None:
+        q = self.sse_queues.get(session_id)
+        if q is not None:
+            q.put_nowait(event)
+
+    def emit_and_push(self, session_id: str, event_type: str, data: dict | None = None) -> dict:
+        event = log.emit(session_id, event_type, data)
+        self.push_event(session_id, event)
+        return event

mad_bros-0.1.0/src/mad/core/workspace.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+
+def workspace_path(session_id: str) -> Path:
+    return Path(tempfile.gettempdir()) / f"mad_{session_id}"
+
+
+def local_path_for_mount(session_id: str, mount_path: str) -> Path:
+    """Map a /workspace/... mount_path into the real temp workspace directory."""
+    relative = mount_path.lstrip("/")
+    if relative.startswith("workspace/") or relative == "workspace":
+        relative = relative[len("workspace"):]
+    relative = relative.lstrip("/")
+    base = workspace_path(session_id)
+    if relative:
+        return base / relative
+    return base

mad_bros-0.1.0/src/mad/providers/__init__.py

@@ -0,0 +1,4 @@
+from mad.providers.base import LLMProvider, ProviderResponse, ToolUse
+from mad.providers.factory import get_provider
+
+__all__ = ["LLMProvider", "ProviderResponse", "ToolUse", "get_provider"]

mad_bros-0.1.0/src/mad/providers/anthropic_api.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from mad.providers.base import LLMProvider, ProviderResponse
+
+
+class AnthropicAPIProvider(LLMProvider):
+    async def complete(self, system: str, messages: list[dict], tools: list[dict]) -> ProviderResponse:
+        raise NotImplementedError("AnthropicAPIProvider not implemented in MVP")

mad_bros-0.1.0/src/mad/providers/base.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+
+@dataclass
+class ToolUse:
+    id: str
+    name: str
+    input: dict
+
+
+@dataclass
+class ProviderResponse:
+    text: str | None = None
+    tool_uses: list[ToolUse] = field(default_factory=list)
+    stop_reason: str = "end_turn"
+
+
+class LLMProvider(Protocol):
+    async def complete(
+        self,
+        system: str,
+        messages: list[dict],
+        tools: list[dict],
+    ) -> ProviderResponse: ...

mad_bros-0.1.0/src/mad/providers/claude_cli.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from mad.providers.base import LLMProvider, ProviderResponse
+
+
+class ClaudeCLIProvider(LLMProvider):
+    async def complete(self, system: str, messages: list[dict], tools: list[dict]) -> ProviderResponse:
+        raise NotImplementedError("ClaudeCLIProvider not implemented in MVP")

mad_bros-0.1.0/src/mad/providers/factory.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from mad.providers.anthropic_api import AnthropicAPIProvider
+from mad.providers.base import LLMProvider
+from mad.providers.claude_cli import ClaudeCLIProvider
+
+
+def get_provider(name: str) -> LLMProvider:
+    if name == "claude_cli":
+        return ClaudeCLIProvider()
+    if name == "anthropic_api":
+        return AnthropicAPIProvider()
+    raise NotImplementedError(f"Unknown provider: {name!r}")

mad_bros-0.1.0/src/mad/providers/fake.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from collections import deque
+
+from mad.providers.base import LLMProvider, ProviderResponse
+
+
+class FakeScriptedProvider(LLMProvider):
+    """Test double that replays a pre-recorded sequence of ProviderResponses."""
+
+    def __init__(self) -> None:
+        self._queue: deque[ProviderResponse] = deque()
+
+    def script(self, responses: list[ProviderResponse]) -> None:
+        self._queue = deque(responses)
+
+    async def complete(self, system: str, messages: list[dict], tools: list[dict]) -> ProviderResponse:
+        if not self._queue:
+            return ProviderResponse(text="(fake provider exhausted)", stop_reason="end_turn")
+        return self._queue.popleft()