# Extend Vifu with plugins

Vifu supports two plugin boundaries:

- **Embedded Runtime integrations** register provider callbacks, Agents, and
  endpoints, and may add Bevy systems through the `vifu` crate's `runtime`
  feature.
- **Runtime service plugins** connect an independent application backend over
  HTTP and JSON-RPC.

Both approaches keep application-specific state, rules, tools, and content
outside the reusable Agent Runtime.

## Embedded Rust plugin

**Status: Available.** Create one `VifuRuntime` for the application, register
its providers, Agents, and named endpoints, and use async calls or the
start/poll/cancel game-loop API. Add a normal Bevy `Plugin` to
`HeadlessRuntime` for application-specific command and effect behavior. Native
iOS and Android hosts use the UniFFI provider callback and embedded Runtime
object. See [Embed the runtime](https://github.com/vifudotdev/vifu/blob/main/docs/runtime-embedding.md).

## Runtime service plugin

**Status: Available.** Vifu can route a project's JSON-RPC requests to an
operator-configured service over ordinary HTTP. Use this boundary when an
application needs an independent state machine, content format, or compiler.

| Vifu | Runtime service plugin |
| --- | --- |
| Canonical project and Agent identity | Application-specific state and rules |
| Project APIs and launch channels | Runtime methods and parameters |
| Provider credentials and Gateway routing | Application-specific release references |
| Agent invocation and traces | Application response and event semantics |

The plugin does not receive provider credentials. When it needs an Agent,
it calls the authenticated Vifu callback for the canonical project and profile.

## Request path

An operator attaches one runtime service plugin to a project. Clients then use:

```text
POST /{project-slug}/v1/rpc
```

Vifu Server validates the JSON-RPC envelope and forwards it to the attached
service. The method names and application payload belong to that plugin.

Static browser clients can use a revocable runtime channel to exchange a
project-scoped launch credential for a short-lived session token. The launch
credential is a public client credential, not an administrator or provider
secret.

## Deployment

The runtime service plugin is a separate process. It can use any implementation
language and storage model as long as it implements the HTTP callback contract.
Vifu Server communicates with it through a configured URL; no cloud-specific
binding is required.

Dynamic third-party native or WebAssembly plugin loading is not yet a supported
public contract.