Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

docs(ruflo-agent): bring README up to date for the managed (cloud) runtime (#1933)

rUv3975ab512c79
diff --git a/plugins/ruflo-agent/README.md b/plugins/ruflo-agent/README.md
index 5db4ab8178..9cc3ab0832 100644
--- a/plugins/ruflo-agent/README.md
+++ b/plugins/ruflo-agent/README.md
@@ -1,6 +1,18 @@
# ruflo-agent
-Sandboxed WASM agent creation, execution, and gallery sharing.
+Agent runtimes for ruflo β€” one mental model, two backends (a third planned):
+
+| Runtime | Tools | Runs on | Trust | Best for |
+|---|---|---|---|---|
+| **WASM** (`rvagent`) | `wasm_agent_*` / `wasm_gallery_*` | local WASM sandbox | sandboxed β€” no host fs/net | untrusted code; portable/replayable RVF containers; fast, free, offline |
+| **Managed** (Anthropic cloud) | `managed_agent_*` | Anthropic-managed container | cloud-isolated | long-running/async tasks; real container with packages + network; persistent filesystem + transcript across turns; no local setup |
+| **SDK** (planned β€” ADR-116) | `sdk_agent_*` | your process / your filesystem | full host trust | a real Claude agent loop (hooks, subagents, MCP, sessions, skills) on the local repo β€” the in-process version of `claude -p`; the killer combo is `mcpServers: { ruflo: { command: "npx", args: ["ruflo","mcp","start"] } }` (a local stdio MCP server β†’ the agent gets ruflo's 314 tools, zero deployment) |
+
+`wasm_agent_*` is the **safe default** (sandboxed). `managed_agent_*` needs `ANTHROPIC_API_KEY` (or `CLAUDE_API_KEY`) + Claude Managed Agents beta access β€” every `managed_agent_*` tool degrades gracefully with a structured "use `wasm_agent_create` for a local no-key runtime" error when the key is absent.
+
+Design: [ADR-115](../../v3/docs/adr/ADR-115-managed-agents-rvagent-backend.md) (the cloud runtime + the planned SDK runtime); [ADR-070](../../v3/implementation/adrs/ADR-070-rvagent-wasm-completion.md) (the WASM runtime); plugin contract [`docs/adrs/0001-wasm-contract.md`](./docs/adrs/0001-wasm-contract.md).
+
+> Renamed from `ruflo-wasm` (it only covered the local WASM runtime). The `wasm_agent_*` / `wasm_gallery_*` tool *names* are unchanged.
## Install
@@ -9,33 +21,20 @@ Sandboxed WASM agent creation, execution, and gallery sharing.
/plugin install ruflo-agent@ruflo
```
-## Features
-
-- **Sandbox isolation**: Agents run in WASM with no host filesystem access
-- **Agent lifecycle**: Create, prompt, configure tools, export, terminate
-- **Community gallery**: Browse, search, and publish WASM agents
-- **Portable**: Export agents that run on any WASM runtime
-
## Commands
-- `/wasm` -- List running agents and browse gallery
+- `/wasm` β€” list running WASM agents and browse the gallery (local runtime)
+- `/managed-agent` β€” list Managed Agent cloud sessions, check status, fetch a transcript, clean up (cloud runtime)
## Skills
-- `wasm-agent` -- Create and manage sandboxed WASM agents
-- `wasm-gallery` -- Browse and publish agents in the community gallery
+- `wasm-agent` β€” create and manage sandboxed WASM agents (local)
+- `wasm-gallery` β€” browse and publish agents in the community gallery
+- `managed-agent` β€” run an Anthropic Claude Managed Agent (cloud) β€” create / prompt / status / events / list / terminate
-## Compatibility
+## MCP surface (16 tools)
-- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
-- **WASM runtime:** built on `@ruvector/rvagent-wasm` + `@ruvector/ruvllm-wasm`. Both are declared in `@claude-flow/cli`'s `optionalDependencies` per [ADR-070 (Implemented)](../../v3/implementation/adrs/ADR-070-rvagent-wasm-completion.md). Without those packages, runtime falls through to the graceful-degradation path and the MCP tools no-op.
-- **Verification:** `bash plugins/ruflo-agent/scripts/smoke.sh` is the contract.
-
-## MCP surface (10 tools)
-
-All defined at `v3/@claude-flow/cli/src/mcp-tools/wasm-agent-tools.ts`:
-
-### Agent lifecycle (7)
+### WASM runtime β€” `v3/@claude-flow/cli/src/mcp-tools/wasm-agent-tools.ts` (10)
| Tool | Purpose |
|------|---------|
@@ -45,41 +44,56 @@ All defined at `v3/@claude-flow/cli/src/mcp-tools/wasm-agent-tools.ts`:
| `wasm_agent_list` | List active WASM agents |
| `wasm_agent_terminate` | Stop a WASM agent |
| `wasm_agent_files` | Read/write files in the sandbox |
-| `wasm_agent_export` | Export agent state |
-
-### Gallery (3)
-
-| Tool | Purpose |
-|------|---------|
+| `wasm_agent_export` | Export agent state (RVF container) |
| `wasm_gallery_list` | Browse community-published WASM agents |
| `wasm_gallery_search` | Search the gallery |
| `wasm_gallery_create` | Publish a WASM agent to the gallery |
-## Sandbox isolation
+### Managed (cloud) runtime β€” `v3/@claude-flow/cli/src/mcp-tools/managed-agent-tools.ts` (6, ADR-115)
-WASM agents run with **no host filesystem access** by default. The `wasm_agent_files` tool exposes a sandboxed virtual filesystem; the host filesystem is not reachable from inside the WASM module.
+| Tool | Purpose | WASM counterpart |
+|------|---------|------------------|
+| `managed_agent_create` | Provision Agent + Environment + Session (`POST /v1/agents`, `/v1/environments`, `/v1/sessions`). Accepts `model` / `system` / `name` / `networking` / `packages` / `initScript` / `mcpServers` / `skills`. | `wasm_agent_create` |
+| `managed_agent_prompt` | Send a user turn (`POST /v1/sessions/{id}/events`), poll until the session goes idle (default 180 s, cap 600 s) β†’ `{finished, status, stopReason, assistantText, toolUses[], eventCount}` | `wasm_agent_prompt` |
+| `managed_agent_status` | Session lifecycle state (idle/running/error, title, last error) | β€” |
+| `managed_agent_events` | Full server-persisted event log + a summary (the transcript/artifact view) | `wasm_agent_files` |
+| `managed_agent_list` | List Managed Agent sessions on the org (id, status, title) β€” see which are still billing | `wasm_agent_list` |
+| `managed_agent_terminate` | `DELETE /v1/sessions/{id}` (Β± the environment) β€” **always call when done**; a cloud session bills container time + tokens until deleted | `wasm_agent_terminate` |
-For prompt-injection defense inside the sandbox, the [ruflo-aidefence 3-gate pattern](../ruflo-aidefence/docs/adrs/0001-aidefence-contract.md) applies to any output flowing back to the host LLM.
+> Beta API (`anthropic-beta: managed-agents-2026-04-01`); `multiagent` / `define-outcomes` on the agent config are research preview. `mcpServers` for a cloud agent must point at a **publicly reachable** URL β€” a local `ruflo mcp start` is not reachable from Anthropic's cloud (deploy/tunnel an HTTP ruflo MCP server first). Managed sessions cost LM tokens + container time and are rate-limited per org.
-## Namespace coordination
+## Compatibility & degradation
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **WASM runtime:** built on `@ruvector/rvagent-wasm` + `@ruvector/ruvllm-wasm` (declared in `@claude-flow/cli`'s `optionalDependencies` per [ADR-070](../../v3/implementation/adrs/ADR-070-rvagent-wasm-completion.md)). Without those packages, the `wasm_agent_*` tools fall through to graceful-degradation no-ops.
+- **Managed runtime:** plain `fetch` against the Managed Agents REST API β€” no extra SDK dependency. Without `ANTHROPIC_API_KEY` / `CLAUDE_API_KEY`, every `managed_agent_*` tool returns a structured error pointing at the `wasm_agent_*` fallback (the CLI/MCP server stays up).
+- **Verification:** `bash plugins/ruflo-agent/scripts/smoke.sh` is the contract (12 structural checks). CI: `.github/workflows/ruflo-agent-smoke.yml`. Behavioral guard for the cloud tools: `v3/@claude-flow/cli/__tests__/managed-agent-tools.test.ts` (no-network).
+
+## Sandbox / trust
+
+WASM agents run with **no host filesystem access** by default; `wasm_agent_files` exposes a sandboxed virtual filesystem only. Managed agents run in Anthropic's cloud container (isolated from your machine). The planned SDK runtime would run in *your* process with full host trust β€” which is why `wasm_agent_*` stays the default and the SDK runtime, when built, will be opt-in.
-This plugin owns the `wasm-gallery` AgentDB namespace (kebab-case, follows the convention from [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md)). Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.
+For prompt-injection defense on output flowing back to the host LLM, the [ruflo-aidefence 3-gate pattern](../ruflo-aidefence/docs/adrs/0001-aidefence-contract.md) applies.
+
+## Namespace coordination
-`wasm-gallery` indexes published WASM agents (manifest, version, signature, download count). Accessed via `memory_*` (namespace-routed).
+This plugin owns the `wasm-gallery` AgentDB namespace (kebab-case, per [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md)). Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed. `wasm-gallery` indexes published WASM agents (manifest, version, signature, download count); accessed via `memory_*` (namespace-routed).
## Verification
```bash
bash plugins/ruflo-agent/scripts/smoke.sh
-# Expected: "11 passed, 0 failed"
+# Expected: "12 passed, 0 failed"
```
## Architecture Decisions
-- [`ADR-0001` β€” ruflo-agent plugin contract (10-tool MCP surface, ADR-070 integration cross-reference, sandbox isolation, smoke as contract)](./docs/adrs/0001-wasm-contract.md)
+- [`ADR-0001` β€” ruflo-agent plugin contract](./docs/adrs/0001-wasm-contract.md) (WASM runtime: 10-tool MCP surface, ADR-070 integration, sandbox isolation, smoke as contract)
+- [`ADR-115`](../../v3/docs/adr/ADR-115-managed-agents-rvagent-backend.md) β€” Claude Managed Agents as the cloud runtime (+ the planned SDK runtime, ADR-116)
## Related Plugins
- `ruflo-agentdb` β€” namespace convention owner
-- `ruflo-aidefence` β€” 3-gate pattern applies to sandbox output flowing back to the host LLM
-- `ruflo-ruvector` β€” the underlying ruvector substrate that ships @ruvector/rvagent-wasm
+- `ruflo-aidefence` β€” 3-gate pattern applies to agent output flowing back to the host LLM
+- `ruflo-ruvector` β€” the ruvector substrate that ships `@ruvector/rvagent-wasm`
+- `ruflo-cost-tracker` β€” record completed Managed Agent sessions (LM tokens + container time)