# Mycelium

> Mycelium is the reliability layer between AI agents and their tools. It prevents unsafe runtime actions after the model proposes a call and before the tool can cause damage. It validates arguments, outputs, paths, entities, destinations, scope, authority, context, budgets, completion state, secrets, and execution state. The authoritative engine is a framework-agnostic Python 3.10+ runtime for LangGraph, CrewAI, or plain Python loops. TypeScript, Go, and any language that can send HTTP/JSON can use the same engine through the experimental local `v1alpha1` sidecar instead of reimplementing its state machine. It complements orchestration and observability; it does not replace them. Keywords: agent runtime safety, tool-call validation, agent guardrails, safe tool execution, agent reliability, language-neutral sidecar.

## What it does

Default execution control (`mycelium init` / `mycelium run`):

- **Duplicate side effects on retry:** classify each tool (`read`, `keyed_mutate`, `non_idempotent_mutate`, etc.), hash a durable transition key, hold a lease (auto-extended while `@ledger` / `@ledger_sync` tools run; default every `lease_ttl / 3`), and resolve duplicates by terminal state: poll reads, hard-block or reconcile ambiguous writes. Disable auto-renew with `lease_renew_interval: 0`.
- **Transition envelope fields:** `side_effect_class` → `capability` → `spendability` → `side_effect_boundary` → `terminal_outcome` → `external_operation_ref` → `retry_permission`. These seven recovery axes tell Mycelium whether another attempt is safe or must stop.

Composable prevention controls (configure or call explicitly):

- **Bad tool calls:** `@bounded` input/output/entity/path checks and `ToolRegistry` allowlists block invalid or out-of-scope calls before execution.
- **Runaway behavior:** `loop_guard` catches repeated action patterns; `budget` enforces duration, step, token, and USD ceilings.
- **Stale or broken context:** `@protect` / `Session`, `MessageValidator`, and `HistoryGuard` validate tool data and conversation structure.
- **Premature completion:** `completion` requires host-declared work before a run may report success.
- **Permission widening:** `scope_guard` freezes the run allowlist and refuses mid-run or handoff expansion.
- **Credentials and destinations:** `secret_args` blocks raw secrets; `entity_guard` restricts write destinations.
- **Destructive authority:** `destructive_confirm`, `authority_window`, and `use_time_currency` require exact, current permission and facts at execution time.
- **Untrusted tool output:** `mark_untrusted_tool_output(value, source=...)` labels tool or retrieved content as `untrusted_data`; marked values cannot become operator-release authorization claims. This is a narrow prompt-injection defense, not full context taint propagation.
- **Verification:** `mycelium doctor` inspects detectable wiring; `mycelium verify` exercises synthetic safety scenarios without calling application tools.
- **Unified state:** one top-level `state_backend` automatically gives loop, scope, completion, state-flush, and audit-receipt guards namespaced atomic storage. Use file on one node and Redis/Postgres across workers.
- **Provider reconciliation:** `mycelium providers verify <adapter>` adversarially tests uncertainty handling and forbidden writes, then emits a signed report bound to the adapter source. Gmail is the only adapter currently shipped; other providers implement a conformance fixture. Reports do not prove live credentials are read-only.
- **Durable composite recovery:** Python applications can wrap an unchanged bounded function with `@composite` when its consequential child calls are already ledgered. Supported shapes are straight-line steps, one boolean branch from an invocation argument or immediately preceding child result, or one top-level `for index in range(N)` with a literal count of 1–32. Each loop iteration has its own child identity; use distinct provider idempotency keys too. Replay returns stored child results; previously unattempted children may run, while ambiguous outcomes reconcile or remain blocked. A stable host-owned operation ID and durable file, SQLite, Redis, or PostgreSQL composite-control storage are required. Redis and PostgreSQL share parent control across workers. The experimental sidecar has a separate `composite-v1` API for explicitly declared steps. General workflow graphs, variable-length or nested loops, and combined branches and loops remain outside the Python decorator's scope.

## Install

```
pip install mycelium-runtime
pip install 'mycelium-runtime[langgraph]'   # optional automatic LangGraph IDs
pip install 'mycelium-runtime[redis]'       # multi-worker / cloud ledger
pip install 'mycelium-runtime[postgres]'    # Postgres ledger backend
mycelium demo              # see the bug and the fix (langgraph#7417)
mycelium init              # transition + one ledgered tool -> mycelium.yaml
mycelium run --config mycelium.yaml -- python -m my_app
```

## TypeScript, Go, and other languages

The engine remains Python. Run it as a small local sidecar, then connect with a
thin client:

```
pip install mycelium-runtime
mycelium sidecar serve --config /absolute/path/sidecar.yaml

npm install @mycelium-labs/sidecar-client@experimental
go get github.com/mycelium-labs/mycelium/clients/go@v0.1.1
```

Java, Rust, C#, Ruby, and other runtimes can call the authenticated OpenAPI
contract directly. Only `EXECUTE` permits the provider call; every other claim
disposition means do not execute. The experimental v1alpha1 protocol supports
a trusted local profile and an explicit shared PostgreSQL profile. It is not a stable production contract or
a public multi-tenant service; clients must report execution boundaries truthfully.

## Coding-agent setup

The source repository ships `.agents/skills/mycelium-setup/SKILL.md`. Ask a
compatible coding agent to “Use `$mycelium-setup` to protect this project.” It
discovers tools, proposes side-effect classifications, fills `mycelium.yaml`,
wires supported runtimes, and runs Doctor and Verify. The developer must still
approve consequential classifications and supply host-owned identities,
secrets, production namespaces, provider credentials, and approval policy.

## Adapter verification

```
export MYCELIUM_ADAPTER_REPORT_SIGNING_KEY='from-your-secret-manager'
mycelium providers verify gmail --key-id provider-ci --output adapter-report.json
mycelium providers verify-report adapter-report.json
```

The signing key is for tamper-evident adapter reports, not normal Mycelium
runtime operation.
## How it differs from Langfuse / LangSmith

Langfuse and LangSmith are observability and tracing. They show what happened after an agent runs. Mycelium is runtime prevention across the tool-call boundary. Use both if you want traces and enforcement.

## Try in 5 minutes

https://mycelium.nandanadileep.com/try.html

```
pip install mycelium-runtime
mycelium demo
mycelium init
mycelium run --config mycelium.yaml -- python -m my_app
```

## Links

- Python workflow recovery: https://mycelium.nandanadileep.com/resolve.html#workflow-recovery
- Agent reliability FAQ: https://mycelium.nandanadileep.com/handbook.html#common-searches
- Duplicate tool call guide: https://mycelium.nandanadileep.com/prevent-duplicate-tool-calls-langgraph.html
- Handbook / docs: https://github.com/mycelium-labs/mycelium/tree/main/sdk/docs
- Try in 5 minutes: https://mycelium.nandanadileep.com/try.html
- PyPI: https://pypi.org/project/mycelium-runtime/
- Source: https://github.com/mycelium-labs/mycelium
- API reference: https://github.com/mycelium-labs/mycelium/blob/main/sdk/README.md
- Language-neutral protocol: https://github.com/mycelium-labs/mycelium/tree/main/sdk/docs/spec
- TypeScript client: https://www.npmjs.com/package/@mycelium-labs/sidecar-client
- Go client: https://pkg.go.dev/github.com/mycelium-labs/mycelium/clients/go
- License: MIT