Metadata-Version: 2.4
Name: agent-loop-guard-runtime
Version: 0.6.0a3
Summary: Local runtime guard for coding agents with loop detection and explainable policy decisions.
Author: Agent Loop Guard contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/RIMUMURUDEV/agent-loop-guard
Project-URL: Repository, https://github.com/RIMUMURUDEV/agent-loop-guard.git
Project-URL: Issues, https://github.com/RIMUMURUDEV/agent-loop-guard/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Security
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: alembic>=1.13
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: jsonschema>=4.23
Requires-Dist: pydantic>=2.8
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: uvicorn[standard]>=0.30
Provides-Extra: mcp
Provides-Extra: bench
Requires-Dist: duckdb>=1.1; extra == "bench"
Requires-Dist: mlflow>=3.0; extra == "bench"
Requires-Dist: pyarrow>=17.0; extra == "bench"
Provides-Extra: sandbox
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Provides-Extra: dev
Requires-Dist: coverage[toml]>=7.6; extra == "dev"
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# Agent Loop Guard

[![CI](https://github.com/RIMUMURUDEV/agent-loop-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/RIMUMURUDEV/agent-loop-guard/actions/workflows/ci.yml)
[![Documentation](https://github.com/RIMUMURUDEV/agent-loop-guard/actions/workflows/docs.yml/badge.svg)](https://rimumurudev.github.io/agent-loop-guard/)
[![PyPI](https://img.shields.io/pypi/v/agent-loop-guard-runtime?label=PyPI)](https://pypi.org/project/agent-loop-guard-runtime/)
[![Python 3.11-3.13](https://img.shields.io/badge/python-3.11--3.13-3776AB.svg)](https://www.python.org/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-2F6F44.svg)](LICENSE)
[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/RIMUMURUDEV.agent-loop-guard-vscode?label=VS%20Code)](https://marketplace.visualstudio.com/items?itemName=RIMUMURUDEV.agent-loop-guard-vscode)

Agent Loop Guard is an Apache-2.0 local safety and observability toolkit for coding agents. It combines a loop guard, MCP permission firewall, session replay, deterministic benchmark lab, and a Docker-backed sandbox technical preview.

The default setup uses a local mock provider, so the demo works without an external API key.

![Agent Loop Guard dashboard](https://raw.githubusercontent.com/RIMUMURUDEV/agent-loop-guard/main/docs/assets/dashboard.png)

## Install

Install the current alpha from [PyPI](https://pypi.org/project/agent-loop-guard-runtime/). The installed command is `alg`:

```bash
pipx install agent-loop-guard-runtime
# or
uv tool install agent-loop-guard-runtime
```

Run once without a permanent installation:

```bash
uvx --from agent-loop-guard-runtime alg doctor
```

For development from this checkout:

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
alg setup
alg doctor
alg guard run
```

Open `http://127.0.0.1:8787`, then run Demo Lab or:

```bash
alg demo exact-loop
```

Default local gateway key:

```text
alg_demo_key
```

## Proxy Endpoints

OpenAI-compatible:

```text
POST /v1/responses
POST /v1/chat/completions
GET  /v1/models
```

Anthropic-compatible:

```text
POST /v1/messages
POST /v1/messages/count_tokens
```

Connectivity probe:

```text
HEAD /
```

Use `Authorization: Bearer alg_demo_key` or `x-api-key: alg_demo_key`.

`alg setup` creates a local YAML configuration and connection profiles for Codex, Claude Code, Cline, and OpenCode under `.agent-loop-guard/profiles`. Open `http://127.0.0.1:8787`, then run Demo Lab or `alg demo exact-loop`.

## Modules

```text
alg setup | doctor | status | open
alg guard run
alg mcp run | serve | validate-policy | test-server
alg replay import | export
alg bench dataset validate | run | compare | regression-check
alg sandbox create | exec | diff | apply | discard | export
```

- **Guard** detects exact request, tool, error, and sequence loops with Shadow and Enforce modes.
- **MCP Firewall** proxies stdio and Streamable HTTP, validates schemas, filters discovery, and applies YAML policies.
- **Replay** stores redacted traces, spans, events, costs, deterministic failure tags, and JSONL/OpenTelemetry exports.
- **Benchmark Lab** runs the bundled 30-task dataset through mock, HTTP, or CLI adapters and computes paired bootstrap confidence intervals.
- **Sandbox Preview** runs a copied workspace in a resource-limited Docker container and applies no changes before explicit approval.

Read the [public documentation](https://rimumurudev.github.io/agent-loop-guard/), [Architecture](docs/architecture.md), [Threat Model](docs/security.md), [Benchmark Guide](docs/guides/benchmark.md), and [Sandbox Guide](docs/guides/sandbox.md). A [Russian overview](docs/ru/index.md) is also available.

## Guard Behavior

The guard implements:

- exact repeated request detection
- repeated tool call detection
- repeated upstream error detection
- repeated request sequence detection
- request and token limits
- project-level Shadow and Enforce modes
- manual session and agent pause/resume
- metadata-only logging by default
- JSON session export and aggregate CSV export
- trace runs, spans, events, replay UI, JSON export, and run comparison

Shadow Mode flags suspicious requests without blocking. Enforce Mode blocks requests when a blocking rule triggers.

## MCP Firewall

Validate and run a stdio policy proxy:

```bash
alg mcp validate-policy app/mcp/presets/filesystem.yml
alg mcp run --policy app/mcp/presets/filesystem.yml -- your-mcp-server
```

For Streamable HTTP, configure a server under `mcp.servers`, run `alg mcp serve`, and connect to `/mcp/{server_id}`. Approval requests appear at `/mcp`. Raw arguments and secrets are redacted; audit records store hashes and policy metadata.

## Session Replay

Every proxied model request now creates a replay trace automatically. Open:

```text
http://127.0.0.1:8787/replay
```

The Replay view shows trace runs, model request spans, policy decision events, token totals, duration, source session links, JSON export, and a simple two-run comparison.

Replay ingest API:

```text
POST /api/v1/traces
POST /api/v1/spans
POST /api/v1/events/batch
GET  /api/v1/runs
GET  /api/v1/runs/{trace_id}
GET  /api/v1/runs/{trace_id}/export?format=json|jsonl|otel
POST /api/v1/runs/import
POST /api/v1/runs/{trace_id}/pin
POST /api/v1/compare
```

CLI transfer:

```bash
alg replay export TRACE_ID --format jsonl --output trace.jsonl
alg replay import trace.jsonl
```

## Benchmark Lab

```bash
alg bench dataset validate
alg bench run --adapter mock --candidate baseline --output baseline.jsonl
alg bench run --adapter mock --variant regressed --candidate candidate --output candidate.jsonl
alg bench regression-check baseline.jsonl candidate.jsonl
```

Parquet, DuckDB, and MLflow are optional:

```bash
pip install -e ".[bench]"
```

The regression command exits `0` for no regression, `1` for a statistically supported regression, and `2` when the result is inconclusive.

## Sandbox Preview

Docker must be installed and running first. The original project is not mounted into the container; the sandbox uses a private copy.

```bash
alg sandbox create .
alg sandbox exec SANDBOX_ID -- pytest -q
alg sandbox diff SANDBOX_ID
alg sandbox apply SANDBOX_ID --path app/example.py
alg sandbox discard SANDBOX_ID
```

Network is disabled by default. This is a defense-in-depth development tool, not a certified security boundary; read [the threat model](docs/security.md) before using it with untrusted code.

Minimal trace ingest example:

```bash
curl -X POST http://127.0.0.1:8787/api/v1/traces ^
  -H "Content-Type: application/json" ^
  -d "{\"trace_id\":\"demo_trace\",\"task_id\":\"demo\",\"spans\":[{\"name\":\"tool.call\",\"start_ns\":1,\"end_ns\":2000000}]}"
```

## Agent Setup

Codex CLI:

```toml
model = "demo-model"
model_provider = "agent_loop_guard"

[model_providers.agent_loop_guard]
name = "Agent Loop Guard"
base_url = "http://127.0.0.1:8787/v1"
env_key = "ALG_GATEWAY_KEY"
```

Claude Code:

```bash
set ANTHROPIC_BASE_URL=http://127.0.0.1:8787
set ANTHROPIC_AUTH_TOKEN=alg_demo_key
```

OpenCode:

```json
{
  "provider": {
    "alg": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Agent Loop Guard",
      "options": {
        "baseURL": "http://127.0.0.1:8787/v1",
        "apiKey": "{env:ALG_GATEWAY_KEY}"
      },
      "models": {
        "demo-model": {"name": "Guarded model"}
      }
    }
  },
  "model": "alg/demo-model"
}
```

Cline:

```text
API Provider: OpenAI Compatible
Base URL: http://127.0.0.1:8787/v1
API Key: alg_demo_key
Model ID: demo-model
```

## VS Code Extension

The VS Code extension starts the local guard daemon, shows health in the status bar, opens dashboard and replay views, and copies agent connection settings.

Install it from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=RIMUMURUDEV.agent-loop-guard-vscode) or from the command line:

```bash
code --install-extension RIMUMURUDEV.agent-loop-guard-vscode
```

Install the Python runtime first, then use `Agent Loop Guard: Setup Current Workspace`:

```bash
pipx install agent-loop-guard-runtime
```

Run the extension from source:

```bash
cd extensions/vscode
npm run check
```

Then open this repository in VS Code, press `F5`, and run `Agent Loop Guard: Start Guard` in the Extension Development Host.

Package and install a local `.vsix`:

```bash
cd extensions/vscode
npm run package
code --install-extension agent-loop-guard-vscode-0.2.0.vsix
```

If `alg` is installed globally, keep `agentLoopGuard.startMode` as `cli`. To run from this checkout instead, set:

```json
{
  "agentLoopGuard.startMode": "source",
  "agentLoopGuard.pythonPath": ".venv\\Scripts\\python.exe",
  "agentLoopGuard.sourcePath": "C:\\path\\to\\agent-loop-guard"
}
```

After the guard is running, point agents at:

```text
OpenAI base URL: http://127.0.0.1:8787/v1
Anthropic base URL: http://127.0.0.1:8787
API key: alg_demo_key
```

See `extensions/vscode/README.md` for all commands and settings.

## Configuration

Create a config file:

```bash
alg init --path agent-loop-guard.yml
```

Run with it:

```bash
alg run --config agent-loop-guard.yml
```

Environment overrides include:

- `ALG_HOST`
- `ALG_PORT`
- `ALG_STORAGE_URL`
- `ALG_MODE`
- `ALG_PROVIDER`
- `ALG_GATEWAY_KEY`
- `ALG_OPENAI_BASE_URL`
- `OPENAI_API_KEY`
- `ALG_ANTHROPIC_BASE_URL`
- `ANTHROPIC_API_KEY`

## Development

```bash
pip install -e ".[dev,docs]"
pytest -q
ruff check .
mkdocs build --strict
```

Run the documentation site locally:

```bash
mkdocs serve
```

The full contributor workflow is in [CONTRIBUTING.md](CONTRIBUTING.md). Security assumptions and private reporting guidance are in [SECURITY.md](SECURITY.md).

Docker:

```bash
docker compose up --build
```

## Project Status

This repository is developed as an educational open-source project. Guard, MCP, Replay, and Benchmark are locally testable. Sandbox is a technical preview and its real Docker smoke-test runs only on Linux CI; it could not be executed on the current Windows machine because Docker is not installed. The Python runtime and VS Code extension are publicly available through PyPI and the VS Code Marketplace.

There is no telemetry, paid cloud, subscription, SLA, or closed feature set. Optional donations may be added later, but they do not influence architecture or priorities.

## Limits

The toolkit only sees traffic routed through it. It does not provide enterprise IAM, distributed leases, legal audit guarantees, a kernel-level isolation guarantee, or hidden chain-of-thought capture. Full Content Logging is off by default and should not be enabled for sensitive data unless the data owner understands the risk.
