> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mob Architecture

> How Meerkat models multi-agent orchestration, member identity, runtime bindings, wiring, flows, and mobpacks.

Mobs are Meerkat's multi-agent runtime. There is no separate sub-agent
substrate: delegation, helper agents, flows, and reusable profiles all compile
to mob members managed by `meerkat-mob`.

## Core Model

```mermaid theme={null}
flowchart TD
    HOST["Host surface"] --> HANDLE["MobHandle"]
    HANDLE --> ACTOR["MobActor"]
    ACTOR --> MACHINE["MobMachine"]
    ACTOR --> STORE["MobStorage"]
    ACTOR --> MEMBERS["Member runtime bindings"]
    MEMBERS --> SESSION["Member sessions"]
    SESSION --> RUNTIME["MeerkatMachine"]
```

`MobActor` serializes mob commands, persists mob state, and projects public
status from `MobMachine` authority. Member sessions are still ordinary Meerkat
sessions, so they inherit provider, tool, auth, memory, and live-channel
behavior from the session runtime.

## Identity

Mob member identity has two layers:

| Identity         | Meaning                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------- |
| `AgentIdentity`  | Stable member identity. Public mob APIs, wiring, delegation, status, and profiles use this. |
| `AgentRuntimeId` | Runtime binding identity. It can rotate on respawn or binding replacement.                  |
| `FenceToken`     | Monotonic binding epoch used to reject stale runtime effects.                               |
| `Generation`     | Member generation counter, incremented on respawn.                                          |

Use `AgentIdentity` for facts that survive respawn. Use `AgentRuntimeId` only
for per-binding runtime facts.

## Runtime Bindings

Members can run as local session-backed agents or as external peers.

| Binding                    | Contract                                                                                                                                                              |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RuntimeBinding::Session`  | Meerkat provisions and owns a local session for the member.                                                                                                           |
| `RuntimeBinding::External` | The host declares the external runtime address, Ed25519 public identity, and typed bootstrap token. The mob derives the real peer id and routes through that runtime. |

External members require an explicit runtime binding. A bare `External` backend
tag is not enough because the runtime needs a concrete process identity before
it can route work or trust peer messages. For a remote `rkat` member, generate
the current binding with `rkat run --comms-listen-tcp ... --comms-binding-out <path>`.

## Public Surfaces

| Surface                          | Mob role                                                                                                                                             |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| CLI `rkat mob ...`               | Helper, artifact, typed callable run, and run-resource commands: `run`, `runs`, `status`, `logs`, `attach`, flow execution, pack, deploy, web build. |
| JSON-RPC `mob/*`                 | Host control plane for mob lifecycle, members, flows, and profiles.                                                                                  |
| REST                             | HTTP adapter for selected mob helper workflows.                                                                                                      |
| MCP `meerkat_mob_*`              | Public MCP control plane.                                                                                                                            |
| Agent tools `mob_*` / `delegate` | Agent-facing delegation and session-owned implicit mobs.                                                                                             |
| Python / TypeScript SDKs         | Typed wrappers over the RPC mob surface.                                                                                                             |
| Web SDK                          | In-browser mob runtime and mobpack deployment target.                                                                                                |

## Flows

Flows are declarative work graphs. They support one-to-one, fan-out, fan-in,
branching, and frame/loop nodes. Flow status is persisted, so a host can check
live state first and fall back to the terminal snapshot.

### WorkGraph Bridge

WorkGraph commitments and Flow runs remain separate authorities. A durable
`WorkExecutionBinding` records the exact effective Flow run configuration and
deterministic run identity before execution. The generated execution lifecycle requests the
launch, observes Mob-owned terminal state, requests evidence projection, and
feeds the WorkGraph closure result back into the binding lifecycle.

The external-delivery ledger is not a second run machine. Its `realizing`
phase is a custody fence, crossed by the Mob actor only after the deterministic
pending `MobRun` is durable. Mob remains the sole owner of run lifecycle. The
ledger prevents blind target reinvocation across an unobserved reply boundary.

Flow success is evidence, not completion authority. WorkGraph's completion
policy remains the only path that can terminalize the commitment. Failed and
canceled runs remain terminal execution attempts and may be superseded by a
new binding while the WorkGraph item stays open.

For multi-host mobs, the binding and WorkGraph store remain on the controlling
host. Remotely placed members execute Flow steps through normal Mob routing;
they do not independently claim or mutate the controlling WorkGraph. Terminal
run observation and evidence projection return to the controlling host, so
distributed execution does not create replicated WorkGraph authority.

## Persistence

Persistent mob state is SQLite/WAL-backed through `SqliteMobStores`.
In-memory storage is used for tests and WASM. The previous exclusive-handle mob
store is gone.

Mobpacks are portable mob artifacts. They package definitions and trust policy
material for deployment through:

```bash theme={null}
rkat mob pack ./mob -o ./dist/mob.mobpack
rkat mob inspect ./dist/mob.mobpack
rkat mob validate ./dist/mob.mobpack --trust-policy permissive
rkat mob run ./dist/mob.mobpack --prompt "run this mob" --trust-policy permissive
rkat mob web build ./dist/mob.mobpack -o ./dist/web --wasm ./meerkat-web-runtime/pkg --trust-policy permissive
```

`mob web build` copies the required prebuilt wasm-pack output into the browser
bundle; it does not compile wasm32.

## Live Channels

Live channels are per session. For a mob member, open `live/open` against that
member's session using a realtime-capable model such as `gpt-realtime-2`.

The old realtime attachment/status plane has been removed. Live channel
lifecycle is caller-initiated through the `live/*` method family.

## Source Pointers

| Area               | Source                                         |
| ------------------ | ---------------------------------------------- |
| Mob actor          | `meerkat-mob/src/runtime/actor.rs`             |
| Mob handle         | `meerkat-mob/src/runtime/handle.rs`            |
| Member identity    | `meerkat-mob/src/ids.rs`                       |
| Storage            | `meerkat-mob/src/store/`                       |
| Agent-facing tools | `meerkat-mob-mcp/src/agent_tools.rs`           |
| Supervisor bridge  | `meerkat-mob/src/runtime/supervisor_bridge.rs` |
| Mobpack            | `meerkat-mob-pack/`                            |

## See Also

* [Mobs concept](/concepts/mobs)
* [Mobs guide](/guides/mobs)
* [Mobpack and Web Deployment](/guides/mobpack)
* [Runtime Architecture](/reference/runtime-architecture)