π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(ruflo-agent): rename ruflo-wasm β ruflo-agent + Claude Managed Agents (cloud) runtime β ADR-115 (proposedβaccepted, implemented) (#1929)
rUvef73a1616fb5
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex 0e696f5214..ab52d5a562 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -72,9 +72,9 @@"description": "Advanced git workflows with diff analysis, risk scoring, and reviewer recommendations"},{- "name": "ruflo-wasm",- "source": "./plugins/ruflo-wasm",- "description": "Sandboxed WASM agent creation, execution, and gallery sharing"+ "name": "ruflo-agent",+ "source": "./plugins/ruflo-agent",+ "description": "Agent runtimes β local WASM-sandboxed agents (rvagent) + Anthropic Claude Managed Agents (cloud); one interface, local-vs-cloud backends"},{"name": "ruflo-workflows",diff --git a/.github/workflows/ruflo-agent-smoke.yml b/.github/workflows/ruflo-agent-smoke.ymlnew file mode 100644index 0000000000..ca1b931a0c--- /dev/null+++ b/.github/workflows/ruflo-agent-smoke.yml@@ -0,0 +1,30 @@+# Structural smoke for the ruflo-agent plugin (local WASM runtime β rvagent β+# plus the Anthropic Managed Agents cloud runtime, ADR-115). No network: it's+# a static check of the plugin manifest, skills, commands, MCP-tool references,+# and ADR cross-references. Triggers on changes to the plugin or this workflow.+name: ruflo-agent-smoke++on:+ push:+ branches: [main, develop, v3]+ paths:+ - 'plugins/ruflo-agent/**'+ - '.github/workflows/ruflo-agent-smoke.yml'+ pull_request:+ branches: [main]+ paths:+ - 'plugins/ruflo-agent/**'+ - '.github/workflows/ruflo-agent-smoke.yml'+ workflow_dispatch:++jobs:+ smoke:+ name: ruflo-agent structural smoke+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-node@v4+ with:+ node-version: '22'+ - name: Run plugin smoke+ run: bash plugins/ruflo-agent/scripts/smoke.shdiff --git a/README.md b/README.mdindex 0fe9e56a54..9b47f82d9b 100644--- a/README.md+++ b/README.md@@ -139,7 +139,7 @@ This adds slash commands and agent definitions only. The Ruflo MCP server is NOT| Plugin | What it does ||--------|-------------|-| **ruflo-wasm** | Run sandboxed WebAssembly agents |+| **ruflo-agent** | Run sandboxed WebAssembly agents || **ruflo-plugin-creator** | Scaffold, validate, and publish your own plugins |#### Domain-Specificdiff --git a/docs/index.md b/docs/index.mdindex 4b11d2d71a..690326c459 100644--- a/docs/index.md+++ b/docs/index.md@@ -39,7 +39,7 @@ RuFlo provides native Claude Code plugins for multi-agent orchestration, /loop w| **ruflo-aidefence** | AI safety scanning, PII detection, prompt defense | `/plugin install ruflo-aidefence@ruflo` || **ruflo-browser** | Playwright browser automation, testing, scraping | `/plugin install ruflo-browser@ruflo` || **ruflo-jujutsu** | Git diff analysis, risk scoring, reviewer recs | `/plugin install ruflo-jujutsu@ruflo` |-| **ruflo-wasm** | Sandboxed WASM agents and gallery sharing | `/plugin install ruflo-wasm@ruflo` |+| **ruflo-agent** | Sandboxed WASM agents and gallery sharing | `/plugin install ruflo-agent@ruflo` || **ruflo-workflows** | Workflow templates, orchestration, lifecycle | `/plugin install ruflo-workflows@ruflo` || **ruflo-daa** | Dynamic Agentic Architecture, cognitive patterns | `/plugin install ruflo-daa@ruflo` || **ruflo-ruvllm** | Local LLM inference, MicroLoRA, chat formatting | `/plugin install ruflo-ruvllm@ruflo` |diff --git a/plugins/README.md b/plugins/README.mdindex 7e02a5fa14..35dacd9e8b 100644--- a/plugins/README.md+++ b/plugins/README.md@@ -60,7 +60,7 @@ claude $(ls -d plugins/ruflo-*/ | sed 's|^|--plugin-dir |' | tr '\n' ' ')| [ruflo-jujutsu](ruflo-jujutsu/) | Diff analysis, risk scoring, reviewer recommendations || [ruflo-docs](ruflo-docs/) | Doc generation, drift detection, API docs || [ruflo-ruvllm](ruflo-ruvllm/) | Local LLM inference, MicroLoRA, chat formatting |-| [ruflo-wasm](ruflo-wasm/) | WASM agent sandboxing and gallery |+| [ruflo-agent](ruflo-agent/) | WASM agent sandboxing and gallery || [ruflo-plugin-creator](ruflo-plugin-creator/) | Scaffold and validate new plugins || [ruflo-migrations](ruflo-migrations/) | Database schema migration management || [ruflo-observability](ruflo-observability/) | Structured logging, tracing, metrics correlation |diff --git a/plugins/ruflo-agent/.claude-plugin/plugin.json b/plugins/ruflo-agent/.claude-plugin/plugin.jsonnew file mode 100644index 0000000000..8d22534304--- /dev/null+++ b/plugins/ruflo-agent/.claude-plugin/plugin.json@@ -0,0 +1,25 @@+{+ "name": "ruflo-agent",+ "description": "Agent runtimes for ruflo \u2014 local WASM-sandboxed agents (rvagent: 10 wasm_agent_*/wasm_gallery_* MCP tools, built on @ruvector/rvagent-wasm + @ruvector/ruvllm-wasm per ADR-070) plus Anthropic Claude Managed Agents as a cloud backend (managed_agent_* MCP tools per ADR-115). One interface, local-vs-cloud runtimes.",+ "version": "0.2.0",+ "author": {+ "name": "ruvnet",+ "url": "https://github.com/ruvnet"+ },+ "homepage": "https://github.com/ruvnet/ruflo",+ "license": "MIT",+ "keywords": [+ "ruflo",+ "agent",+ "rvagent",+ "rvagent-wasm",+ "ruvllm-wasm",+ "wasm",+ "sandbox",+ "managed-agents",+ "anthropic",+ "cloud",+ "mcp",+ "gallery"+ ]+}diff --git a/plugins/ruflo-wasm/README.md b/plugins/ruflo-agent/README.mdsimilarity index 89%rename from plugins/ruflo-wasm/README.mdrename to plugins/ruflo-agent/README.mdindex 86dccc484e..5db4ab8178 100644--- a/plugins/ruflo-wasm/README.md+++ b/plugins/ruflo-agent/README.md@@ -1,4 +1,4 @@-# ruflo-wasm+# ruflo-agentSandboxed WASM agent creation, execution, and gallery sharing.@@ -6,7 +6,7 @@ Sandboxed WASM agent creation, execution, and gallery sharing.```/plugin marketplace add ruvnet/ruflo-/plugin install ruflo-wasm@ruflo+/plugin install ruflo-agent@ruflo```## Features@@ -29,7 +29,7 @@ Sandboxed WASM agent creation, execution, and gallery sharing.- **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-wasm/scripts/smoke.sh` is the contract.+- **Verification:** `bash plugins/ruflo-agent/scripts/smoke.sh` is the contract.## MCP surface (10 tools)@@ -70,13 +70,13 @@ This plugin owns the `wasm-gallery` AgentDB namespace (kebab-case, follows the c## Verification```bash-bash plugins/ruflo-wasm/scripts/smoke.sh+bash plugins/ruflo-agent/scripts/smoke.sh# Expected: "11 passed, 0 failed"```## Architecture Decisions-- [`ADR-0001` β ruflo-wasm 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 (10-tool MCP surface, ADR-070 integration cross-reference, sandbox isolation, smoke as contract)](./docs/adrs/0001-wasm-contract.md)## Related Pluginsdiff --git a/plugins/ruflo-wasm/agents/wasm-specialist.md b/plugins/ruflo-agent/agents/wasm-specialist.mdsimilarity index 100%rename from plugins/ruflo-wasm/agents/wasm-specialist.mdrename to plugins/ruflo-agent/agents/wasm-specialist.mddiff --git a/plugins/ruflo-agent/commands/managed-agent.md b/plugins/ruflo-agent/commands/managed-agent.mdnew file mode 100644index 0000000000..cd2454a253--- /dev/null+++ b/plugins/ruflo-agent/commands/managed-agent.md@@ -0,0 +1,13 @@+---+name: managed-agent+description: Anthropic Claude Managed Agents (cloud runtime) β list cloud sessions, check status, fetch a transcript, clean up+---++Manage Claude Managed Agent sessions (the cloud agent runtime; the local WASM runtime is the `/wasm` command).++1. Call `mcp__claude-flow__managed_agent_list` to show every Managed Agent session on this org (id, status, title) β note which are still `running` (i.e. still billing).+2. For a specific session: `mcp__claude-flow__managed_agent_status` `{ sessionId }` (idle/running/error) and `mcp__claude-flow__managed_agent_events` `{ sessionId }` (full transcript + a summary: assistantText, toolUses).+3. To run new work: `mcp__claude-flow__managed_agent_create` then `mcp__claude-flow__managed_agent_prompt` (see the `managed-agent` skill for the full flow + the cost/cleanup notes).+4. Clean up stale sessions: `mcp__claude-flow__managed_agent_terminate` `{ sessionId, environmentId? }` β a cloud session bills until deleted.++If `managed_agent_*` returns "needs ANTHROPIC_API_KEY" β no key/beta access; use the local `/wasm` runtime instead.diff --git a/plugins/ruflo-wasm/commands/wasm.md b/plugins/ruflo-agent/commands/wasm.mdsimilarity index 100%rename from plugins/ruflo-wasm/commands/wasm.mdrename to plugins/ruflo-agent/commands/wasm.mddiff --git a/plugins/ruflo-wasm/docs/adrs/0001-wasm-contract.md b/plugins/ruflo-agent/docs/adrs/0001-wasm-contract.mdsimilarity index 80%rename from plugins/ruflo-wasm/docs/adrs/0001-wasm-contract.mdrename to plugins/ruflo-agent/docs/adrs/0001-wasm-contract.mdindex 5545b538fe..6f1585629a 100644--- a/plugins/ruflo-wasm/docs/adrs/0001-wasm-contract.md+++ b/plugins/ruflo-agent/docs/adrs/0001-wasm-contract.md@@ -1,6 +1,6 @@---id: ADR-0001-title: ruflo-wasm plugin contract β pinning, namespace coordination, ADR-070 integration cross-reference, smoke as contract+title: ruflo-agent plugin contract β pinning, namespace coordination, ADR-070 integration cross-reference, smoke as contractstatus: Accepteddate: 2026-05-04updated: 2026-05-09@@ -11,7 +11,7 @@ tags: [plugin, wasm, sandbox, gallery, namespace, smoke-test]## Context-`ruflo-wasm` (v0.1.0) β sandboxed WASM agent creation, execution, and gallery sharing. 1 agent (`wasm-specialist`), 2 skills (`wasm-agent`, `wasm-gallery`), 1 command (`/wasm`).+`ruflo-agent` (v0.1.0) β sandboxed WASM agent creation, execution, and gallery sharing. 1 agent (`wasm-specialist`), 2 skills (`wasm-agent`, `wasm-gallery`), 1 command (`/wasm`).Wraps **10 `wasm_*` MCP tools** at `v3/@claude-flow/cli/src/mcp-tools/wasm-agent-tools.ts:18, 51, 74, 103, 117, 138, 160, 181, 195, 216`:@@ -48,7 +48,7 @@ Wraps **10 `wasm_*` MCP tools** at `v3/@claude-flow/cli/src/mcp-tools/wasm-agent## Verification```bash-bash plugins/ruflo-wasm/scripts/smoke.sh+bash plugins/ruflo-agent/scripts/smoke.sh# Expected: "11 passed, 0 failed"```@@ -61,4 +61,4 @@ bash plugins/ruflo-wasm/scripts/smoke.sh## Implementation status-Plugin version v0.2.0 shipped and listed in marketplace.json. Source exists at `plugins/ruflo-wasm/`. Contract elements implemented: all 10 `wasm_*` MCP tools covered; ADR-070 (rvagent WASM completion) cross-referenced; 3-gate pattern alignment with ruflo-aidefence documented for sandboxed prompt-injection defense; namespace `wasm-agents` claimed; smoke-as-contract gate defined in `scripts/smoke.sh` (11 checks).+Plugin version v0.2.0 shipped and listed in marketplace.json. Source exists at `plugins/ruflo-agent/`. Contract elements implemented: all 10 `wasm_*` MCP tools covered; ADR-070 (rvagent WASM completion) cross-referenced; 3-gate pattern alignment with ruflo-aidefence documented for sandboxed prompt-injection defense; namespace `wasm-agents` claimed; smoke-as-contract gate defined in `scripts/smoke.sh` (11 checks).diff --git a/plugins/ruflo-wasm/scripts/smoke.sh b/plugins/ruflo-agent/scripts/smoke.shsimilarity index 64%rename from plugins/ruflo-wasm/scripts/smoke.shrename to plugins/ruflo-agent/scripts/smoke.shindex a7fdef1309..200716dbf3 100755--- a/plugins/ruflo-wasm/scripts/smoke.sh+++ b/plugins/ruflo-agent/scripts/smoke.sh@@ -7,12 +7,17 @@ step() { printf "β %s ... " "$1"; }ok() { printf "PASS\n"; PASS=$((PASS+1)); }bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }-step "1. plugin.json declares 0.2.0 with new keywords"-v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)-if [[ "$v" != "0.2.0" ]]; then bad "expected 0.2.0, got '$v'"; else+step "1. plugin.json is ruflo-agent 0.2.0 with both-runtime keywords"+P="$ROOT/.claude-plugin/plugin.json"+v=$(grep -E '"version"' "$P" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)+n=$(grep -E '"name"' "$P" | grep -oE 'ruflo-agent' | head -1)+if [[ "$v" != "0.2.0" ]]; then bad "expected version 0.2.0, got '$v'";+elif [[ "$n" != "ruflo-agent" ]]; then bad "expected name ruflo-agent";+elsemiss=""- for k in mcp rvagent-wasm ruvllm-wasm; do- grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"+ # local WASM runtime (rvagent) + cloud runtime (managed-agents) keywords+ for k in mcp rvagent-wasm ruvllm-wasm managed-agents anthropic; do+ grep -q "\"$k\"" "$P" || miss="$miss $k"done[[ -z "$miss" ]] && ok || bad "missing keywords:$miss"fi@@ -71,10 +76,10 @@ grep -q "ruflo-aidefence" "$F" \&& grep -qE "3-gate|3 gates" "$F" \&& ok || bad "AIDefence 3-gate cross-reference missing"-step "10. ADR-0001 exists with status Proposed"+step "10. ADR-0001 exists with status Accepted"ADR="$ROOT/docs/adrs/0001-wasm-contract.md"-[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR" \- && ok || bad "ADR missing or status != Proposed"+[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Accepted" "$ADR" \+ && ok || bad "ADR missing or status != Accepted"step "11. no wildcard tool grants in skills"bad_skills=""@@ -83,5 +88,17 @@ for f in "$ROOT"/skills/*/SKILL.md; dodone[[ -z "$bad_skills" ]] && ok || bad "wildcard:$bad_skills"+step "12. managed-agent (cloud runtime) skill + command + all 6 managed_agent_* tools referenced (ADR-115)"+miss=""+[[ -f "$ROOT/skills/managed-agent/SKILL.md" ]] || miss="$miss missing-skill"+[[ -f "$ROOT/commands/managed-agent.md" ]] || miss="$miss missing-command"+for t in managed_agent_create managed_agent_prompt managed_agent_status managed_agent_events managed_agent_list managed_agent_terminate; do+ grep -rq "$t" "$ROOT/skills" "$ROOT/commands" || miss="$miss no-ref-$t"+done+# the cloud-runtime skill must keep an explicit allowed-tools list (no wildcard) and offer the wasm fallback+grep -q '^allowed-tools:[[:space:]]*\*' "$ROOT/skills/managed-agent/SKILL.md" 2>/dev/null && miss="$miss wildcard"+grep -q 'wasm_agent_create' "$ROOT/skills/managed-agent/SKILL.md" 2>/dev/null || miss="$miss no-wasm-fallback-ref"+[[ -z "$miss" ]] && ok || bad "$miss"+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"[[ $FAIL -eq 0 ]] || exit 1diff --git a/plugins/ruflo-agent/skills/managed-agent/SKILL.md b/plugins/ruflo-agent/skills/managed-agent/SKILL.mdnew file mode 100644index 0000000000..8f1b27f04e--- /dev/null+++ b/plugins/ruflo-agent/skills/managed-agent/SKILL.md@@ -0,0 +1,56 @@+---+name: managed-agent+description: Run an Anthropic Claude Managed Agent β a cloud agent harness (container + filesystem + tools), the cloud counterpart of the local wasm-agent runtime+argument-hint: "<create|prompt|status|events|list|terminate> [options]"+allowed-tools: mcp__claude-flow__managed_agent_create mcp__claude-flow__managed_agent_prompt mcp__claude-flow__managed_agent_status mcp__claude-flow__managed_agent_events mcp__claude-flow__managed_agent_list mcp__claude-flow__managed_agent_terminate mcp__claude-flow__wasm_agent_create Bash+---++# Managed Agent (Anthropic cloud runtime)++`ruflo-agent` has two agent runtimes behind one mental model:++| Runtime | Tools | Use it when |+|---|---|---|+| **WASM** (local, `rvagent`) | `wasm_agent_*` / `wasm_gallery_*` | fast, free, ephemeral, offline, untrusted code in a sandbox |+| **Managed** (Anthropic cloud) | `managed_agent_*` (this skill) | long-running / async work (minutesβhours), a real cloud container with pre-installed packages + network, persistent filesystem + transcript across turns |++This skill drives the **managed** runtime β Anthropic's [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) (beta). The model: **Agent** (model + system + tools + MCP servers + skills) β **Environment** (container template) β **Session** (running instance) β **Events** (turns / tool-use / status, persisted server-side). See `docs/adr/0001-wasm-contract.md` and project ADR-115.++## Prerequisites++- `ANTHROPIC_API_KEY` (or `CLAUDE_API_KEY`) in the environment, with Claude Managed Agents beta access.+- If absent, every `managed_agent_*` tool returns a structured "use `wasm_agent_create` for a local no-key runtime" error β fall back to the WASM skill.++## Steps++1. **Create** β `mcp__claude-flow__managed_agent_create`+ `{ model?, system?, name?, networking?, packages?, initScript?, mcpServers?, skills? }`+ β `{ sessionId, agentId, environmentId, status }`. Provisions Agent + Environment + Session. Save the three ids.+ - `mcpServers`: `[{type:"url", url, name, authorization_token?}]` β the cloud agent must be able to *reach* the URL. A local `ruflo mcp start` is **not** reachable from Anthropic's cloud; deploy/tunnel an HTTP ruflo MCP server first if you want the cloud agent to have ruflo's tools.+ - `packages`: `{pip?:[], npm?:[], apt?:[], cargo?:[], gem?:[], go?:[]}` β installed in the container.++2. **Prompt** β `mcp__claude-flow__managed_agent_prompt`+ `{ sessionId, message, maxWaitMs? }` β sends a user turn, polls the event log until the session goes idle (default 180s, capped 600s) β `{ finished, status, stopReason, assistantText, toolUses[], eventCount }`. For very long tasks, raise `maxWaitMs` or follow up with `managed_agent_events`.++3. **Inspect** β `mcp__claude-flow__managed_agent_status` `{ sessionId }` (idle/running/error) Β· `mcp__claude-flow__managed_agent_events` `{ sessionId, raw? }` (full transcript: user turns, agent thinking, tool_use, tool_result, status β the cloud counterpart of `wasm_agent_files`).++4. **List** β `mcp__claude-flow__managed_agent_list` `{ limit? }` β every session on the org (so you can see which are still running / billing).++5. **Terminate** β `mcp__claude-flow__managed_agent_terminate` `{ sessionId, environmentId? }` β **always do this when done**: a cloud session keeps billing container time + tokens until deleted. Pass `environmentId` to also delete the environment ruflo created.++## Cost & safety++- Managed Agents bill per session (LM tokens + container time) and are rate-limited per org. Estimate before a long run; record completed sessions to the `cost-tracking` namespace.+- Treat orphaned sessions like leaked resources β `managed_agent_list` then `managed_agent_terminate` anything stale.+- Beta API (`managed-agents-2026-04-01`); `multiagent` / `define-outcomes` on the agent config are research preview.++## Quick example++```+managed_agent_create { "model": "claude-haiku-4-5-20251001", "system": "Terse. Do exactly what is asked.", "name": "scratch" }+ β { sessionId: "sesn_β¦", agentId: "agent_β¦", environmentId: "env_β¦", status: "idle" }+managed_agent_prompt { "sessionId": "sesn_β¦", "message": "echo hello > /tmp/x && cat /tmp/x β then stop." , "maxWaitMs": 60000 }+ β { finished: true, status: "idle", stopReason: "end_turn", assistantText: "Done.", toolUses: [{name:"bash", input:{command:"echo hello > /tmp/x && cat /tmp/x"}}] }+managed_agent_terminate { "sessionId": "sesn_β¦", "environmentId": "env_β¦" }+ β { sessionDeleted: true, environmentDeleted: true }+```diff --git a/plugins/ruflo-wasm/skills/wasm-agent/SKILL.md b/plugins/ruflo-agent/skills/wasm-agent/SKILL.mdsimilarity index 100%rename from plugins/ruflo-wasm/skills/wasm-agent/SKILL.mdrename to plugins/ruflo-agent/skills/wasm-agent/SKILL.mddiff --git a/plugins/ruflo-wasm/skills/wasm-gallery/SKILL.md b/plugins/ruflo-agent/skills/wasm-gallery/SKILL.mdsimilarity index 100%rename from plugins/ruflo-wasm/skills/wasm-gallery/SKILL.mdrename to plugins/ruflo-agent/skills/wasm-gallery/SKILL.mddiff --git a/plugins/ruflo-core/skills/discover-plugins/SKILL.md b/plugins/ruflo-core/skills/discover-plugins/SKILL.mdindex a537aef34d..f4d31267e3 100644--- a/plugins/ruflo-core/skills/discover-plugins/SKILL.md+++ b/plugins/ruflo-core/skills/discover-plugins/SKILL.md@@ -70,7 +70,7 @@ When starting a new project, exploring ruflo capabilities, or wondering which pl| **ruflo-jujutsu** | PR review, merge decisions, diff risk scoring | Diff analysis, risk classification, reviewer recommendations || **ruflo-docs** | After API changes, before releases | Doc generation, drift detection, API documentation || **ruflo-ruvllm** | Local LLM inference, custom model configs | RuVLLM integration, MicroLoRA fine-tuning, chat formatting |-| **ruflo-wasm** | Sandboxed code execution, untrusted workloads | WASM agent sandboxing, community gallery |+| **ruflo-agent** | Sandboxed code execution, untrusted workloads | WASM agent sandboxing, community gallery || **ruflo-plugin-creator** | Building new ruflo plugins | Scaffold structure, validate frontmatter, test MCP references || **ruflo-migrations** | Database schema changes | Sequential migration numbering, up/down pairs, dry-run, rollback validation || **ruflo-observability** | Logging, tracing, metrics correlation | Structured JSON logging, distributed tracing, agent-to-app telemetry correlation |diff --git a/plugins/ruflo-wasm/.claude-plugin/plugin.json b/plugins/ruflo-wasm/.claude-plugin/plugin.jsondeleted file mode 100644index cc617b4f4a..0000000000--- a/plugins/ruflo-wasm/.claude-plugin/plugin.json+++ /dev/null@@ -1,21 +0,0 @@-{- "name": "ruflo-wasm",- "description": "Sandboxed WASM agent creation, execution, and gallery sharing β wraps 10 wasm_* MCP tools (agent_create/prompt/tool/list/terminate/files/export + gallery_list/search/create); built on @ruvector/rvagent-wasm + @ruvector/ruvllm-wasm per ADR-070 (Implemented)",- "version": "0.2.0",- "author": {- "name": "ruvnet",- "url": "https://github.com/ruvnet"- },- "homepage": "https://github.com/ruvnet/ruflo",- "license": "MIT",- "keywords": [- "ruflo",- "wasm",- "sandbox",- "agents",- "gallery",- "mcp",- "rvagent-wasm",- "ruvllm-wasm"- ]-}diff --git a/ruflo/README.md b/ruflo/README.mdindex 0fe9e56a54..9b47f82d9b 100644--- a/ruflo/README.md+++ b/ruflo/README.md@@ -139,7 +139,7 @@ This adds slash commands and agent definitions only. The Ruflo MCP server is NOT| Plugin | What it does ||--------|-------------|-| **ruflo-wasm** | Run sandboxed WebAssembly agents |+| **ruflo-agent** | Run sandboxed WebAssembly agents || **ruflo-plugin-creator** | Scaffold, validate, and publish your own plugins |#### Domain-Specificdiff --git a/v3/@claude-flow/cli/README.md b/v3/@claude-flow/cli/README.mdindex 0fe9e56a54..9b47f82d9b 100644--- a/v3/@claude-flow/cli/README.md+++ b/v3/@claude-flow/cli/README.md@@ -139,7 +139,7 @@ This adds slash commands and agent definitions only. The Ruflo MCP server is NOT| Plugin | What it does ||--------|-------------|-| **ruflo-wasm** | Run sandboxed WebAssembly agents |+| **ruflo-agent** | Run sandboxed WebAssembly agents || **ruflo-plugin-creator** | Scaffold, validate, and publish your own plugins |#### Domain-Specificdiff --git a/v3/@claude-flow/cli/__tests__/managed-agent-tools.test.ts b/v3/@claude-flow/cli/__tests__/managed-agent-tools.test.tsnew file mode 100644index 0000000000..1bcce3b8ed--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/managed-agent-tools.test.ts@@ -0,0 +1,92 @@+/**+ * Guard for ADR-115 β the managed_agent_* MCP tools (Claude Managed Agents+ * cloud runtime, in the `ruflo-agent` plugin). No-network: every handler must+ * short-circuit with a structured "needs ANTHROPIC_API_KEY β use wasm_agent_*"+ * error when no key is set, so the CLI/MCP server stays up offline.+ */+import { describe, it, expect, beforeEach, afterEach } from 'vitest';+import { managedAgentTools } from '../src/mcp-tools/managed-agent-tools.js';++const TOOL_NAMES = [+ 'managed_agent_create',+ 'managed_agent_prompt',+ 'managed_agent_status',+ 'managed_agent_events',+ 'managed_agent_list',+ 'managed_agent_terminate',+] as const;++const tool = (name: string) => {+ const t = managedAgentTools.find(t => t.name === name);+ if (!t) throw new Error(`managed-agent tool not registered: ${name}`);+ return t;+};++describe('ADR-115 β managed_agent_* MCP tools', () => {+ let prevAnth: string | undefined;+ let prevClaude: string | undefined;++ beforeEach(() => {+ prevAnth = process.env.ANTHROPIC_API_KEY;+ prevClaude = process.env.CLAUDE_API_KEY;+ delete process.env.ANTHROPIC_API_KEY;+ delete process.env.CLAUDE_API_KEY;+ });+ afterEach(() => {+ if (prevAnth === undefined) delete process.env.ANTHROPIC_API_KEY; else process.env.ANTHROPIC_API_KEY = prevAnth;+ if (prevClaude === undefined) delete process.env.CLAUDE_API_KEY; else process.env.CLAUDE_API_KEY = prevClaude;+ });++ it('registers exactly the six managed_agent_* tools', () => {+ const names = managedAgentTools.map(t => t.name).sort();+ expect(names).toEqual([...TOOL_NAMES].sort());+ });++ it('every tool has an inputSchema (object) and an ADR-112-ish description that mentions the wasm_agent_* / native fallback', () => {+ for (const t of managedAgentTools) {+ expect(t.inputSchema?.type).toBe('object');+ expect(typeof t.description).toBe('string');+ expect(t.description.length).toBeGreaterThanOrEqual(80);+ // each description should orient the caller toward wasm_agent_* / native when that's the right call+ expect(t.description).toMatch(/wasm_agent_|native/);+ expect(t.category).toBe('agent');+ }+ });++ it('descriptions are unique (no copy-paste)', () => {+ const descs = managedAgentTools.map(t => t.description);+ expect(new Set(descs).size).toBe(descs.length);+ });++ for (const name of TOOL_NAMES) {+ it(`${name} degrades gracefully with no API key (no throw, structured error, no network)`, async () => {+ // minimal valid-ish input per tool's required fields+ const input: Record<string, unknown> =+ name === 'managed_agent_prompt' ? { sessionId: 's', message: 'm' }+ : name === 'managed_agent_create' ? {}+ : name === 'managed_agent_list' ? {}+ : { sessionId: 's' };+ const res = (await (tool(name).handler as any)(input)) as Record<string, unknown>;+ expect(res).toBeTruthy();+ expect(String(res.error ?? '')).toMatch(/ANTHROPIC_API_KEY/);+ expect(String(res.error ?? '')).toMatch(/wasm_agent_create/);+ // tools that report success should report it false+ if ('success' in res) expect(res.success).toBe(false);+ // list-shaped tools still return an empty list+ if (name === 'managed_agent_list') {+ expect(res.sessions).toEqual([]);+ expect(res.total).toBe(0);+ }+ });+ }++ it('managed_agent_prompt rejects missing sessionId/message (with a key set, but no network call made)', async () => {+ process.env.ANTHROPIC_API_KEY = 'sk-ant-test-not-real';+ const noSession = await (tool('managed_agent_prompt').handler as any)({ message: 'hi' });+ expect(noSession.success).toBe(false);+ expect(String(noSession.error)).toMatch(/sessionId/);+ const noMessage = await (tool('managed_agent_prompt').handler as any)({ sessionId: 's' });+ expect(noMessage.success).toBe(false);+ expect(String(noMessage.error)).toMatch(/message/);+ });+});diff --git a/v3/@claude-flow/cli/src/mcp-client.ts b/v3/@claude-flow/cli/src/mcp-client.tsindex 062ed508bb..2f3d81ffce 100644--- a/v3/@claude-flow/cli/src/mcp-client.ts+++ b/v3/@claude-flow/cli/src/mcp-client.ts@@ -42,6 +42,10 @@ import { agentdbTools } from './mcp-tools/agentdb-tools.js';// RuVector WASM toolsimport { ruvllmWasmTools } from './mcp-tools/ruvllm-tools.js';import { wasmAgentTools } from './mcp-tools/wasm-agent-tools.js';+// ADR-115: Anthropic Claude Managed Agents β a cloud agent runtime alongside+// the local WASM-sandboxed `wasm_agent_*` (rvagent) tools. Lives in the+// `ruflo-agent` plugin.+import { managedAgentTools } from './mcp-tools/managed-agent-tools.js';import { guidanceTools } from './mcp-tools/guidance-tools.js';import { autopilotTools } from './mcp-tools/autopilot-tools.js';// #1916: coverage-aware routing tools β defined in ruvector/coverage-tools.ts@@ -118,6 +122,8 @@ registerTools([// RuVector WASM tools...ruvllmWasmTools,...wasmAgentTools,+ // ADR-115: Anthropic Claude Managed Agents (cloud agent runtime)+ ...managedAgentTools,// Guidance & discovery tools...guidanceTools,// Autopilot persistent completion toolsdiff --git a/v3/@claude-flow/cli/src/mcp-tools/managed-agent-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/managed-agent-tools.tsnew file mode 100644index 0000000000..132af04c01--- /dev/null+++ b/v3/@claude-flow/cli/src/mcp-tools/managed-agent-tools.ts@@ -0,0 +1,359 @@+/**+ * Managed Agent MCP tools β Anthropic Claude Managed Agents as a *cloud*+ * agent runtime alongside ruflo's local WASM-sandboxed agents (`rvagent` /+ * `wasm_agent_*`). See ADR-115.+ *+ * Wraps the Managed Agents REST API (beta, `anthropic-beta:+ * managed-agents-2026-04-01`) with plain `fetch` β no new SDK dependency.+ * Needs `ANTHROPIC_API_KEY` (or `CLAUDE_API_KEY`); every tool degrades+ * gracefully with a structured error when the key is absent so the CLI/MCP+ * server stays up.+ *+ * Lifecycle (mirrors `wasm_agent_*`):+ * managed_agent_create β agents.create + environments.create + sessions.create β wasm_agent_create+ * managed_agent_prompt β events.send(user.message) + poll events until idle β wasm_agent_prompt+ * managed_agent_status β GET /v1/sessions/{id}+ * managed_agent_events β GET /v1/sessions/{id}/events (full transcript) β wasm_agent_files (artifacts/log)+ * managed_agent_list β GET /v1/sessions+ * managed_agent_terminateβ DELETE /v1/sessions/{id} (+ optionally the env) β wasm_agent_terminate+ */++import type { MCPTool } from './types.js';++const API_BASE = process.env.ANTHROPIC_BASE_URL?.replace(/\/$/, '') || 'https://api.anthropic.com';+const BETA_HEADER = 'managed-agents-2026-04-01';+const ANTHROPIC_VERSION = '2023-06-01';+const DEFAULT_MODEL = 'claude-sonnet-4-6';+const POLL_INTERVAL_MS = 1500;+const DEFAULT_MAX_WAIT_MS = 180_000; // 3 min β long enough for a real task, bounded so a tool call never hangs forever++function apiKey(): string | null {+ return process.env.ANTHROPIC_API_KEY || process.env.CLAUDE_API_KEY || null;+}++function headers(key: string): Record<string, string> {+ return {+ 'x-api-key': key,+ 'anthropic-version': ANTHROPIC_VERSION,+ 'anthropic-beta': BETA_HEADER,+ 'content-type': 'application/json',+ };+}++const NEEDS_KEY = {+ error:+ 'managed-agent runtime needs ANTHROPIC_API_KEY (or CLAUDE_API_KEY) and Claude Managed Agents beta access. ' ++ 'For a local, no-key agent runtime use wasm_agent_create instead (rvagent / WASM sandbox).',+};++async function maRequest<T = unknown>(+ method: 'GET' | 'POST' | 'DELETE',+ path: string,+ body?: unknown,+): Promise<{ ok: true; status: number; data: T } | { ok: false; status: number; error: string; body?: unknown }> {+ const key = apiKey();+ if (!key) return { ok: false, status: 0, error: NEEDS_KEY.error };+ let res: Response;+ try {+ res = await fetch(`${API_BASE}/v1${path}`, {+ method,+ headers: headers(key),+ body: body !== undefined ? JSON.stringify(body) : undefined,+ signal: AbortSignal.timeout(30_000),+ });+ } catch (e) {+ return { ok: false, status: 0, error: `network error calling ${method} /v1${path}: ${(e as Error).message}` };+ }+ const text = await res.text();+ let parsed: unknown = undefined;+ try { parsed = text ? JSON.parse(text) : undefined; } catch { /* leave undefined */ }+ if (!res.ok) {+ const apiErr = (parsed as { error?: { message?: string }; message?: string })?.error?.message+ ?? (parsed as { message?: string })?.message+ ?? text.slice(0, 300);+ return { ok: false, status: res.status, error: `Managed Agents API ${res.status}: ${apiErr}`, body: parsed };+ }+ return { ok: true, status: res.status, data: parsed as T };+}++// ---- shapes (only the fields we touch) -----------------------------------+interface MaAgent { id: string; version?: number; name?: string; model?: { id: string } }+interface MaEnvironment { id: string; name?: string; config?: unknown }+interface MaSession { id: string; status?: string; title?: string; error?: string | null; agent?: MaAgent; environment_id?: string }+interface MaEvent { type: string; content?: Array<{ type: string; text?: string }>; name?: string; input?: unknown; id?: string; processed_at?: string; stop_reason?: { type: string } }++// ---- helpers --------------------------------------------------------------+function summarizeEvents(events: MaEvent[]): {+ assistantText: string;+ toolUses: Array<{ name: string; input: unknown }>;+ status: string;+ stopReason: string | null;+ eventCount: number;+} {+ let assistantText = '';+ const toolUses: Array<{ name: string; input: unknown }> = [];+ let status = 'unknown';+ let stopReason: string | null = null;+ for (const e of events) {+ if (e.type === 'agent.message' && Array.isArray(e.content)) {+ assistantText += e.content.filter(b => b.type === 'text').map(b => b.text ?? '').join('');+ } else if (e.type === 'agent.tool_use') {+ toolUses.push({ name: e.name ?? '?', input: e.input });+ } else if (e.type === 'session.status_running') {+ status = 'running';+ } else if (e.type === 'session.status_idle') {+ status = 'idle';+ stopReason = e.stop_reason?.type ?? null;+ } else if (e.type === 'session.status_error' || e.type === 'session.status_failed') {+ status = 'error';+ }+ }+ return { assistantText, toolUses, status, stopReason, eventCount: events.length };+}++async function fetchSessionEvents(sessionId: string): Promise<MaEvent[]> {+ const r = await maRequest<{ data?: MaEvent[]; events?: MaEvent[] }>('GET', `/sessions/${encodeURIComponent(sessionId)}/events`);+ if (!r.ok) return [];+ const d = r.data;+ return (d.data ?? d.events ?? []) as MaEvent[];+}++// Wait until the session is no longer "running": poll the event log for a+// terminal session.status_* event. Bounded by maxWaitMs.+async function waitForIdle(sessionId: string, maxWaitMs: number): Promise<{ done: boolean; events: MaEvent[] }> {+ const deadline = Date.now() + Math.max(1_000, Math.min(maxWaitMs, 600_000));+ let events: MaEvent[] = [];+ while (Date.now() < deadline) {+ events = await fetchSessionEvents(sessionId);+ const terminal = events.some(e => e.type === 'session.status_idle' || e.type === 'session.status_error' || e.type === 'session.status_failed');+ // Also stop early if the session record itself reports a non-running status+ if (terminal) return { done: true, events };+ await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));+ }+ return { done: false, events };+}++function maName(prefix: string, given?: unknown): string {+ if (typeof given === 'string' && given.trim()) return given.trim().slice(0, 80);+ return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;+}++// ---------------------------------------------------------------------------++export const managedAgentTools: MCPTool[] = [+ {+ name: 'managed_agent_create',+ description:+ 'Spin up an Anthropic-managed cloud agent (Agent + Environment + Session) β the CLOUD counterpart of wasm_agent_create. Use when wasm_agent_create (local WASM sandbox) is wrong because the task is long-running/async (minutes-hours), needs a real cloud container with pre-installed packages + network, or persistent filesystem + transcript across turns. For a fast, free, ephemeral, offline agent use wasm_agent_create (rvagent). Needs ANTHROPIC_API_KEY + Managed Agents beta access. Returns {sessionId, agentId, environmentId}; pair with managed_agent_prompt.',+ category: 'agent',+ inputSchema: {+ type: 'object',+ properties: {+ name: { type: 'string', description: 'Agent name (default: auto)' },+ model: { type: 'string', description: 'Model id (default: claude-sonnet-4-6)' },+ system: { type: 'string', description: 'System prompt' },+ title: { type: 'string', description: 'Session title' },+ mcpServers: {+ type: 'array',+ description: 'MCP servers to expose to the agent β each {type:"url", url, name, authorization_token?}. NOTE: the cloud agent must be able to *reach* the URL (a local `ruflo mcp start` is not reachable from Anthropic\'s cloud β deploy/tunnel it).',+ items: { type: 'object' },+ },+ skills: { type: 'array', description: 'Skills to attach to the agent', items: { type: 'object' } },+ packages: { type: 'object', description: 'Environment packages: {pip?:[], npm?:[], apt?:[], cargo?:[], gem?:[], go?:[]}' },+ networking: { type: 'string', enum: ['unrestricted', 'restricted', 'none'], description: 'Environment networking (default: unrestricted)' },+ initScript: { type: 'string', description: 'Environment init script (bash, run at container start)' },+ },+ },+ handler: async (input) => {+ if (!apiKey()) return { success: false, ...NEEDS_KEY };++ // 1. Agent+ const agentBody: Record<string, unknown> = {+ name: maName('ruflo-managed', input.name),+ model: typeof input.model === 'string' && input.model ? input.model : DEFAULT_MODEL,+ tools: [{ type: 'agent_toolset_20260401' }],+ };+ if (typeof input.system === 'string') agentBody.system = input.system;+ if (Array.isArray(input.mcpServers) && input.mcpServers.length) agentBody.mcp_servers = input.mcpServers;+ if (Array.isArray(input.skills) && input.skills.length) agentBody.skills = input.skills;+ const a = await maRequest<MaAgent>('POST', '/agents', agentBody);+ if (!a.ok) return { success: false, stage: 'agent', error: a.error };++ // 2. Environment+ const net = (input.networking as string) || 'unrestricted';+ const envBody: Record<string, unknown> = {+ name: maName('ruflo-managed-env', input.name),+ config: { type: 'cloud', networking: { type: net } },+ };+ if (input.packages && typeof input.packages === 'object') (envBody.config as Record<string, unknown>).packages = { type: 'packages', ...(input.packages as object) };+ if (typeof input.initScript === 'string' && input.initScript) (envBody.config as Record<string, unknown>).init_script = input.initScript;+ const e = await maRequest<MaEnvironment>('POST', '/environments', envBody);+ if (!e.ok) return { success: false, stage: 'environment', agentId: a.data.id, error: e.error };++ // 3. Session+ const s = await maRequest<MaSession>('POST', '/sessions', {+ agent: a.data.id,+ environment_id: e.data.id,+ title: maName('ruflo-managed session', input.title),+ });+ if (!s.ok) return { success: false, stage: 'session', agentId: a.data.id, environmentId: e.data.id, error: s.error };++ return {+ success: true,+ runtime: 'managed',+ sessionId: s.data.id,+ agentId: a.data.id,+ agentVersion: a.data.version,+ environmentId: e.data.id,+ status: s.data.status ?? 'idle',+ model: agentBody.model,+ note: 'Cloud agent provisioned. Send work with managed_agent_prompt({sessionId, message}); inspect with managed_agent_events; clean up with managed_agent_terminate (it bills container time + tokens until you do).',+ };+ },+ },+ {+ name: 'managed_agent_prompt',+ description:+ 'Send a user turn to a managed cloud-agent session and wait for it to go idle, returning the assistant text + a tool-use trace β the CLOUD counterpart of wasm_agent_prompt. Use when wasm_agent_prompt (local WASM) is wrong because the work is long-running, needs the cloud container, or must persist across turns. Polls the session event log up to maxWaitMs (default 180s); for very long tasks raise maxWaitMs or follow up with managed_agent_events. Pair with managed_agent_create (for sessionId).',+ category: 'agent',+ inputSchema: {+ type: 'object',+ properties: {+ sessionId: { type: 'string', description: 'Session id from managed_agent_create' },+ message: { type: 'string', description: 'The user turn / task for the agent' },+ maxWaitMs: { type: 'number', description: 'Max ms to wait for the session to go idle (default 180000, capped at 600000)' },+ },+ required: ['sessionId', 'message'],+ },+ handler: async (input) => {+ if (!apiKey()) return { success: false, ...NEEDS_KEY };+ const sessionId = String(input.sessionId ?? '');+ const message = String(input.message ?? '');+ if (!sessionId) return { success: false, error: 'sessionId is required' };+ if (!message) return { success: false, error: 'message is required' };++ const send = await maRequest('POST', `/sessions/${encodeURIComponent(sessionId)}/events`, {+ events: [{ type: 'user.message', content: [{ type: 'text', text: message }] }],+ });+ if (!send.ok) return { success: false, stage: 'send', sessionId, error: send.error };++ const maxWait = typeof input.maxWaitMs === 'number' && input.maxWaitMs > 0 ? input.maxWaitMs : DEFAULT_MAX_WAIT_MS;+ const { done, events } = await waitForIdle(sessionId, maxWait);+ const sum = summarizeEvents(events);+ return {+ success: true,+ runtime: 'managed',+ sessionId,+ finished: done,+ status: sum.status,+ stopReason: sum.stopReason,+ assistantText: sum.assistantText,+ toolUses: sum.toolUses,+ eventCount: sum.eventCount,+ note: done+ ? undefined+ : `Session still running after ${maxWait}ms β call managed_agent_events({sessionId}) to keep watching, or managed_agent_prompt again to steer.`,+ };+ },+ },+ {+ name: 'managed_agent_status',+ description:+ 'Get the lifecycle state of a managed cloud-agent session: idle/running/error, title, last error. Use when native conversation memory is wrong because you need the cloud session\'s server-side status across turns rather than guessing. For a local WASM agent use wasm_agent_list. Pair with managed_agent_events for the full transcript.',+ category: 'agent',+ inputSchema: { type: 'object', properties: { sessionId: { type: 'string', description: 'Session id' } }, required: ['sessionId'] },+ handler: async (input) => {+ if (!apiKey()) return { ...NEEDS_KEY };+ const sessionId = String(input.sessionId ?? '');+ if (!sessionId) return { error: 'sessionId is required' };+ const r = await maRequest<MaSession>('GET', `/sessions/${encodeURIComponent(sessionId)}`);+ if (!r.ok) return { sessionId, error: r.error };+ return { runtime: 'managed', sessionId: r.data.id, status: r.data.status, title: r.data.title, error: r.data.error ?? null, environmentId: r.data.environment_id };+ },+ },+ {+ name: 'managed_agent_events',+ description:+ 'Fetch the full server-persisted event log of a managed cloud-agent session (user turns, agent thinking, tool_use, tool_result, status) β the transcript/artifact view, the CLOUD counterpart of wasm_agent_files. Use when native Read is wrong because the work happened in Anthropic\'s cloud container, not on disk. For a local WASM agent\'s filesystem use wasm_agent_files. Returns the events plus a summary (assistantText, toolUses).',+ category: 'agent',+ inputSchema: {+ type: 'object',+ properties: {+ sessionId: { type: 'string', description: 'Session id' },+ raw: { type: 'boolean', description: 'Include the full raw event objects (default: summary + compact list)' },+ },+ required: ['sessionId'],+ },+ handler: async (input) => {+ if (!apiKey()) return { ...NEEDS_KEY };+ const sessionId = String(input.sessionId ?? '');+ if (!sessionId) return { error: 'sessionId is required' };+ const events = await fetchSessionEvents(sessionId);+ const sum = summarizeEvents(events);+ const compact = events.map(e => {+ if (e.type === 'agent.message') return { type: e.type, text: (e.content ?? []).filter(b => b.type === 'text').map(b => b.text ?? '').join('').slice(0, 500) };+ if (e.type === 'agent.tool_use') return { type: e.type, name: e.name, input: e.input };+ if (e.type === 'agent.tool_result') return { type: e.type, content: JSON.stringify(e.content ?? {}).slice(0, 500) };+ return { type: e.type, ...(e.stop_reason ? { stop_reason: e.stop_reason } : {}) };+ });+ return {+ runtime: 'managed',+ sessionId,+ status: sum.status,+ stopReason: sum.stopReason,+ assistantText: sum.assistantText,+ toolUses: sum.toolUses,+ eventCount: sum.eventCount,+ events: input.raw ? events : compact,+ };+ },+ },+ {+ name: 'managed_agent_list',+ description:+ 'List managed cloud-agent sessions on this Anthropic org (id, status, title) β the CLOUD counterpart of wasm_agent_list. Use when native conversation memory is wrong because you need to see which cloud sessions exist (and which are still running / billing) across turns. For local WASM agents use wasm_agent_list. Pair with managed_agent_terminate to clean up idle sessions.',+ category: 'agent',+ inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'Max sessions to return (default 50)' } } },+ handler: async (input) => {+ if (!apiKey()) return { ...NEEDS_KEY, sessions: [], total: 0 };+ const limit = typeof input.limit === 'number' && input.limit > 0 ? Math.min(Math.floor(input.limit), 200) : 50;+ const r = await maRequest<{ data?: MaSession[]; sessions?: MaSession[] }>('GET', `/sessions?limit=${limit}`);+ if (!r.ok) return { sessions: [], total: 0, error: r.error };+ const list = (r.data.data ?? r.data.sessions ?? []) as MaSession[];+ return {+ runtime: 'managed',+ sessions: list.map(s => ({ sessionId: s.id, status: s.status, title: s.title, environmentId: s.environment_id })),+ total: list.length,+ };+ },+ },+ {+ name: 'managed_agent_terminate',+ description:+ 'Delete a managed cloud-agent session (stops billing for it) β the CLOUD counterpart of wasm_agent_terminate. Use when native nothing applies because a cloud session keeps billing container time + tokens until deleted. For a local WASM agent use wasm_agent_terminate. Optionally also deletes the session\'s environment. Always call this when done with a managed agent.',+ category: 'agent',+ inputSchema: {+ type: 'object',+ properties: {+ sessionId: { type: 'string', description: 'Session id to delete' },+ environmentId: { type: 'string', description: 'Optional: also delete this environment (the one returned by managed_agent_create)' },+ },+ required: ['sessionId'],+ },+ handler: async (input) => {+ if (!apiKey()) return { success: false, ...NEEDS_KEY };+ const sessionId = String(input.sessionId ?? '');+ if (!sessionId) return { success: false, error: 'sessionId is required' };+ const s = await maRequest('DELETE', `/sessions/${encodeURIComponent(sessionId)}`);+ const result: Record<string, unknown> = { runtime: 'managed', sessionId, sessionDeleted: s.ok };+ if (!s.ok) result.error = s.error;+ if (typeof input.environmentId === 'string' && input.environmentId) {+ const e = await maRequest('DELETE', `/environments/${encodeURIComponent(String(input.environmentId))}`);+ result.environmentDeleted = e.ok;+ if (!e.ok) result.environmentError = e.error;+ }+ result.success = s.ok;+ return result;+ },+ },+];diff --git a/v3/docs/adr/ADR-115-managed-agents-rvagent-backend.md b/v3/docs/adr/ADR-115-managed-agents-rvagent-backend.mdnew file mode 100644index 0000000000..cf097082c2--- /dev/null+++ b/v3/docs/adr/ADR-115-managed-agents-rvagent-backend.md@@ -0,0 +1,155 @@+# ADR-115 β Claude Managed Agents as a cloud backend for `rvagent`++**Status**: Accepted (2026-05-12) β implemented as the `managed_agent_*` MCP tools in the `ruflo-agent` plugin (see Implementation below)+**Date**: 2026-05-12+**Authors**: claude (drafted with rUv)+**Related**: `ruflo-agent` plugin (renamed from `ruflo-wasm`) / `wasm_agent_*` MCP tools (`@ruvector/rvagent-wasm`) Β· ADR-026 (3-tier model routing) Β· ADR-095 G2 / ADR-104 (pluggable `ConsensusTransport` / `FederationTransport`) Β· ADR-097 (federation peers) Β· ADR-112 (MCP tool discoverability) Β· [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)+**Supersedes**: nothing++## Context++Ruflo's `rvagent` capability β the `ruflo-agent` plugin, wrapping `@ruvector/rvagent-wasm` β is a *local, WASM-sandboxed* agent harness. Its MCP surface:++| `rvagent` tool | What it does |+|---|---|+| `wasm_agent_create` | spin up a WASM-sandboxed agent (its own filesystem, tools) |+| `wasm_agent_prompt` | send the agent a user turn |+| `wasm_agent_tool` | invoke a tool inside the sandbox |+| `wasm_agent_files` | read the sandbox filesystem |+| `wasm_agent_export` | export the session as an RVF container (portable, replayable) |+| `wasm_agent_terminate` | stop the agent |+| `wasm_gallery_*` | publish / discover reusable agent templates |++[Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) (Anthropic, beta β `anthropic-beta: managed-agents-2026-04-01`) is a *cloud, Anthropic-managed* agent harness with the **same conceptual model**:++| Managed Agents concept | API |+|---|---|+| **Agent** β model + system + tools + MCP servers + skills | `POST /v1/agents` β `{id, version}` (reusable by id, versioned) |+| **Environment** β container template (apt/pip/npm/cargo/gem/go packages, networking, init script, env vars) | `POST /v1/environments` β `{id}` |+| **Session** β a running agent instance in an environment | `POST /v1/sessions` `{agent, environment_id, title}` β `{id, status}` |+| **Events** β user turns / tool use / tool results / status, SSE-streamed and persisted | `POST /v1/sessions/{id}/events`, `GET /v1/sessions/{id}/stream` (SSE), `GET /v1/sessions/{id}/events` (full history) |+| Built-in toolset (`agent_toolset_20260401`): bash, file ops (read/write/edit/glob/grep), web search/fetch, MCP servers | per-tool config + `permission_policy` |++It also exposes `mcp_servers`, `skills`, `multiagent` (research preview), and **define-outcomes** (research preview) on the agent config β i.e. Anthropic is converging on the same primitives ruflo already has (agents, MCP servers, skills, multi-agent swarms, success criteria).++The mapping to `rvagent` is essentially 1:1:++| `rvagent` (WASM, local) | Managed Agents (cloud) |+|---|---|+| `wasm_agent_create` (sandbox) | `agents.create` + `environments.create` + `sessions.create` |+| `wasm_agent_prompt` | `events.send(user.message)` + `events.stream` |+| (tools run inside the WASM sandbox) | the agent autonomously calls `agent_toolset_20260401` tools in the cloud container |+| `wasm_agent_files` | bash/file tools in the container; full event history is `GET /sessions/{id}/events` |+| `wasm_agent_export` (RVF container) | session + event history is persisted server-side; export = the event log |+| `wasm_agent_terminate` | `DELETE /v1/sessions/{id}` (or the session goes idle) |+| WASM sandbox (local, no network unless granted) | cloud container (`environments`, networking rules) |+| `wasm_gallery_*` (share agent templates) | agents are reusable-by-id; a "gallery" entry = the agent-config blob |++### Validation (this exploration)++A live smoke against `https://api.anthropic.com/v1` with the org's Anthropic key (sourced from the GCP `claude-flow/anthropic-api-key` secret) confirmed the flow end-to-end:++```+POST /v1/agents {name, model:"claude-haiku-4-5-20251001", system, tools:[{type:"agent_toolset_20260401"}]} β agent_β¦ (version 1)+POST /v1/environments {name, config:{type:"cloud", networking:{type:"unrestricted"}}} β env_β¦+POST /v1/sessions {agent, environment_id, title} β sesn_β¦ (status:"idle")+POST /v1/sessions/{id}/events {events:[{type:"user.message", content:[{type:"text", text:"echo β¦ > /tmp/x && cat /tmp/x"}]}]}+GET /v1/sessions/{id}/events β 13 events: session.status_running β user.message β agent.thinking β agent.tool_use(bash) β+ agent.tool_result("ruflo-managed-agents-smoke OK\n") β agent.message("Done.") β session.status_idle (stop_reason:end_turn)+DELETE /v1/sessions/{id}, DELETE /v1/environments/{id} (cleanup)+```++Roughly ~7 s wall-clock for a trivial bash task on Haiku. The container provisioned, ran the agent loop, executed the tool, and went idle without intervention. Headers required on every request: `x-api-key`, `anthropic-version: 2023-06-01`, `anthropic-beta: managed-agents-2026-04-01`. The SSE stream returns nothing if you attach it *after* a fast session already went idle β `GET /sessions/{id}/events` is the reliable transcript; attach the stream before/while sending the user event for real-time.++## Decision++**Treat `rvagent` as the *interface* and add Claude Managed Agents as a second *backend* behind it β a `runtime: "managed"` (vs the default `"wasm"`) on the `wasm_agent_*` MCP tools** (and/or a thin `managed_agent_*` alias toolset), wrapping the Managed Agents REST API via `@anthropic-ai/sdk`'s `client.beta.agents|environments|sessions` (which sets the beta header automatically). This mirrors the established ruflo pattern of one interface over a local-vs-cloud transport (`ConsensusTransport`: `LocalTransport` | `FederationTransport` β ADR-095 G2 / ADR-104).++### Surface++- `wasm_agent_create({ runtime: "managed", model?, system?, mcpServers?, skills?, env? })` β creates (or reuses) a Managed Agent + environment + session; returns a handle that looks like a WASM-agent handle (`agentId` β session id, plus the underlying `agent`/`environment` ids) so downstream tools don't care which backend it is.+- `wasm_agent_prompt({ agentId, runtime: "managed", message })` β `events.send(user.message)` then drain `events.stream` (or poll `events`) until `session.status_idle`; returns the assistant text + a tool-use trace.+- `wasm_agent_files({ agentId, runtime: "managed" })` β fetch the session's file artifacts / event history.+- `wasm_agent_terminate({ agentId, runtime: "managed" })` β `DELETE /v1/sessions/{id}` (and optionally the env).+- `wasm_gallery_*` β store/retrieve Managed-Agent **config blobs** (`{model, system, tools, mcp_servers, skills}`) alongside the existing WASM-agent templates; a gallery entry that targets `runtime: "managed"` materializes a real Managed Agent on use.++### The high-value combinations++1. **Ruflo's own MCP server as a Managed Agent tool source.** Managed Agents' agent config accepts `mcp_servers`. A ruflo Managed Agent can be wired to `npx ruflo mcp start` (HTTP transport) β the cloud agent gets ruflo's 314 MCP tools (memory, swarm, hooks, agentdb, federation, β¦) running in the cloud container. That is: a cloud-hosted ruflo agent, no local infra.+2. **Managed Agents as a federation peer (ADR-097/104).** A Managed Agent session is, operationally, a remote autonomous executor with persisted state β the same shape as a federated peer. The `FederationTransport` / `task_assign` dispatch could target a Managed Agent session as one of its executors (closing the #1916 "task-execution dispatch" gap with a *third* executor option: local WASM | federated peer | Anthropic Managed).+3. **Long-running / async work.** `rvagent`-WASM is in-process and ephemeral; Managed Agents persist a filesystem + event history across interactions and run for minutes/hours β the right backend for long agent tasks where the WASM sandbox isn't.+4. **Skills + outcomes parity.** Managed Agents accept ruflo's skills (Markdown skill files) and (research-preview) `define-outcomes` β a Managed-Agent backed `rvagent` can carry the same skill set and success criteria a local one does.++### Constraints / boundaries++- **Optional, off by default.** `runtime: "wasm"` stays the default; `runtime: "managed"` requires `ANTHROPIC_API_KEY` (or the GCP `anthropic-api-key` secret in CI/ops) and the beta header β degrade gracefully (`{ error: "managed runtime needs ANTHROPIC_API_KEY + managed-agents beta access" }`) when absent. No core package gains a hard dependency on `@anthropic-ai/sdk` for this β it's a plugin-level dep (`ruflo-agent` / a new `ruflo-managed-agents`), lazily imported.+- **Cost & rate limits.** Managed Agents bill per session (LM tokens + container time) and are rate-limited per org (create: 300/min, read: 600/min) plus tier spend limits. The tool descriptions must say so (ADR-112), and `cost-tracking` should record Managed-Agent sessions the same way it records LM calls. `wasm_agent_prompt({runtime:"managed"})` should surface an estimated cost before a long run.+- **Beta churn.** The API is beta (`managed-agents-2026-04-01`); `multiagent` and `define-outcomes` are research preview. Pin the beta header in one place; treat the latter two as feature-flagged.+- **Branding.** Anthropic's branding guidelines forbid presenting a Managed-Agents integration as "Claude Code"/"Claude Cowork" β ruflo keeps its own branding; surface it as "ruflo agent (Anthropic Managed runtime)" not "Claude Code agent".+- **Cleanup discipline.** A Managed Agent leaves an `agent` + `environment` + `session` on the org account; `wasm_agent_terminate` must delete the session (and env, if ruflo created it), and there should be a `managed_agent_gc` / doctor check for orphaned sessions.++This ADR records the *intent to build*; the plugin's internals (exact handle shape, stream-vs-poll, gallery storage, federation wiring) are a follow-up implementation PR.++### Future: a third runtime β the Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`)++This ADR adds the *cloud* runtime (Managed Agents). There's a natural *third* runtime that completes the spectrum: the **[Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview)** (`@anthropic-ai/claude-agent-sdk` for TS, `claude-agent-sdk` for Python) β "Claude Code as a library": `query({prompt, options})` / `ClaudeSDKClient`, with built-in tools (Read/Write/Edit/Bash/Glob/Grep/WebSearch/WebFetch/Monitor/AskUserQuestion), hooks (`PreToolUse`/`PostToolUse`/`Stop`/`SessionStart`/β¦), subagents (`agents` option + the `Agent` tool), MCP servers (`mcpServers` option), permission modes (`permissionMode`/`allowedTools`), sessions (resume/fork), and it loads Claude Code's filesystem config (`.claude/skills/*/SKILL.md`, `.claude/commands/*.md`, `CLAUDE.md`, plugins). It bundles a native Claude Code binary. **Runs in your process, on your filesystem** β full host trust.++So `ruflo-agent` would expose three runtimes behind one mental model:++| Runtime | Package | Runs on | Trust | Best for |+|---|---|---|---|---|+| **WASM** (`rvagent`) | `@ruvector/rvagent-wasm` | local WASM sandbox | sandboxed (no host fs/net) | untrusted code; portable/replayable RVF containers; fast, free, offline |+| **SDK** (`sdk_agent_*`, future) | `@anthropic-ai/claude-agent-sdk` | your process / your filesystem | full host trust | a real Claude agent loop (hooks, subagents, MCP, sessions, skills) on the local repo/services β the programmatic, in-process version of `claude -p` |+| **Managed** (`managed_agent_*`, this ADR) | Managed Agents REST API | Anthropic cloud container | cloud-isolated | long-running/async; managed infra; no local setup; persistent server-side session |++Why the SDK runtime is worth adding (a follow-up β likely its own ADR-116):+- It **is** Claude Code's machinery, exposed as a library β and ruflo already loads `.claude/skills`, `.claude/commands`, `CLAUDE.md`, plugins, and shells out to `claude -p`. The SDK is the in-process version: full control over the message stream, hooks (ruflo's own hooks), subagents (ruflo's 16 roles), MCP servers, permission modes, sessions.+- The "give the agent ruflo's 314 tools" combo is **trivial** here (unlike Managed Agents, which needs a publicly reachable URL): pass `mcpServers: { ruflo: { command: "npx", args: ["ruflo", "mcp", "start"] } }` β a *local* stdio MCP server, no deployment.+- Anthropic positions it as "prototype with the Agent SDK locally β move to Managed Agents for production" β having both in `ruflo-agent` gives ruflo exactly that path.++Costs/constraints (so it stays opt-in, plugin-level, off by default β `wasm_agent_*` remains the safe default): a real, heavy dependency (bundles a Claude Code binary as an optional dep); **full host trust, no sandbox** β the least-isolated of the three (a WASM agent can't touch your fs; an SDK agent can); needs `ANTHROPIC_API_KEY` (or Bedrock/Vertex/Azure creds). Branding rules (not "Claude Code").++## Consequences++### Positive++- **One mental model, two runtimes.** Authors think "rvagent"; ruflo picks local WASM (fast, free, ephemeral, no network) or Anthropic Managed (cloud, persistent, long-running, no local infra) per task β like it already picks `LocalTransport` vs `FederationTransport`.+- **Closes a real gap.** A cloud autonomous executor with persisted state and a full toolset is exactly what `task_assign` / hive workers (#1916 items 3/4) and long-running federation tasks need; Managed Agents is a turnkey option.+- **Ruflo-tools-in-the-cloud.** Wiring `npx ruflo mcp start` as a Managed Agent's MCP server gives a cloud-hosted ruflo with zero local setup β a strong onboarding/demo story and a real ops capability.+- **First-party, low integration cost.** It's Anthropic's own API; `@anthropic-ai/sdk` is already in the dep tree somewhere; the conceptual mapping is 1:1 so the adapter is thin. Validated working today.+- **Convergent primitives.** Managed Agents' agent/environment/session/events/skills/mcp_servers/multiagent/outcomes are the same primitives ruflo has β the integration is "speak the same nouns to a different harness", not an impedance mismatch.++### Negative++- **Cost surface.** Easy to rack up container-time + token spend; needs cost-tracking integration + pre-run estimates + a GC for orphaned sessions, or it becomes a footgun.+- **Beta exposure.** Wire shapes may shift; `multiagent`/`outcomes` are research-preview (gated). Maintenance burden until GA.+- **Two backends to keep behaviorally aligned.** `runtime: "wasm"` and `runtime: "managed"` must return compatible handle/result shapes; divergence (e.g. `wasm_agent_files` semantics) is a latent bug source β code review and a parity smoke (run the same trivial task on both runtimes, diff the result shape) are needed.+- **Network/credential dependency.** `managed` runtime can't work offline or without an Anthropic key + beta access; the WASM runtime is the floor.++### Neutral++- Opt-in; users who don't use `managed_agent_*` see no change. Worst case: an unused code path behind an env-var.+- This is "adopt an external standard" (Anthropic's harness), not invent one β same posture as ADR-114 (DSPy.ts).++## Implementation (2026-05-12)++Landed as a **separate `managed_agent_*` toolset** (rather than a `runtime:` flag on the existing `wasm_agent_*` tools β cleaner, zero risk to the WASM path; both toolsets now live in the renamed `ruflo-agent` plugin):++- `plugins/ruflo-wasm/` β **`plugins/ruflo-agent/`** (`git mv`; `plugin.json` name/description/keywords now span both runtimes; `.claude-plugin/marketplace.json` entry + READMEs + `discover-plugins` skill + `verification/inventory.json` updated). The `wasm_agent_*` / `wasm_gallery_*` tool *names* are unchanged.+- **`v3/@claude-flow/cli/src/mcp-tools/managed-agent-tools.ts`** β 6 new MCP tools, registered in `mcp-client.ts`, wrapping the Managed Agents REST API with plain `fetch` (no new SDK dep): `managed_agent_create` (`agents.create` + `environments.create` + `sessions.create`), `managed_agent_prompt` (`events.send(user.message)` + poll `GET /events` until a terminal `session.status_*`, default 180 s / cap 600 s), `managed_agent_status`, `managed_agent_events` (full transcript + a summary), `managed_agent_list`, `managed_agent_terminate` (`DELETE /sessions/{id}` Β± the env). Key from `ANTHROPIC_API_KEY` / `CLAUDE_API_KEY`; every tool degrades gracefully with a structured "use `wasm_agent_create` for a local no-key runtime" error when absent. ADR-112-compliant descriptions (each names when `wasm_agent_*` / native is the right call instead). `mcpServers` / `skills` / `packages` / `networking` / `initScript` pass through to the agent/environment config.+- **`plugins/ruflo-agent/skills/managed-agent/SKILL.md`** + **`commands/managed-agent.md`** β the cloud-runtime skill/command (the WASM-vs-managed decision table, the key prereq + fallback, the `mcpServers`-reachability caveat, the cost/cleanup discipline).+- **`plugins/ruflo-agent/scripts/smoke.sh`** + **`.github/workflows/ruflo-agent-smoke.yml`** β structural CI guard (12 checks now: manifest is `ruflo-agent` with both-runtime keywords; all 10 `wasm_*` + all 6 `managed_agent_*` referenced; managed-agent skill keeps an explicit `allowed-tools` + offers the `wasm_agent_create` fallback; ADR cross-refs). Also wired into the `audit-cli-mcp-tools` / `audit-tool-descriptions` guards (311 registered / 0 dangling / 0 no-guidance).++**Validated live** against `api.anthropic.com` with the org's Anthropic key (GCP `claude-flow/anthropic-api-key`), via `ruflo mcp exec -t managed_agent_*`: `create` (haiku, custom system) β `{sessionId, agentId, environmentId, status:"idle", model:"claude-haiku-4-5-20251001"}`; `prompt` ("echo β¦ > /tmp/r.txt && cat β¦") β `{finished:true, status:"idle", stopReason:"end_turn", assistantText:"Done.", toolUses:[{name:"bash", input:{command:"echo β¦ && cat β¦"}}], eventCount:13}`; `terminate` β `{sessionDeleted:true, environmentDeleted:true}`. No-key path returns the graceful error. `claude --plugin-dir plugins/ruflo-agent` loads the plugin and lists its skills (`managed-agent`, `wasm-agent`, `wasm-gallery`). `smoke.sh` 12/0; cli build clean.++**Not yet done (follow-ups, called out above):** `runtime:"managed"` as a flag on `wasm_agent_*` (unification); a deployed/tunneled HTTP ruflo MCP server so the cloud agent gets ruflo's 314 tools (the combo needs a reachable URL); `task_assign` / federation dispatch to a Managed Agent session (#1916 items 3/4 β a third executor); cost-tracking integration + a `doctor`/GC check for orphaned sessions; `multiagent` / `define-outcomes` (research-preview, feature-flagged).++## Links++- Claude Managed Agents β overview: https://platform.claude.com/docs/en/managed-agents/overview Β· quickstart: https://platform.claude.com/docs/en/managed-agents/quickstart Β· sessions API: https://platform.claude.com/docs/en/managed-agents/sessions Β· tools: https://platform.claude.com/docs/en/managed-agents/tools+- `@ruvector/rvagent-wasm` (the `rvagent` backend) β dep of `@claude-flow/cli`; surfaced via the `ruflo-agent` plugin's `wasm_agent_*` MCP tools+- ADR-095 G2 / ADR-104 β pluggable `ConsensusTransport` / `FederationTransport` (the local-vs-cloud pattern this reuses)+- ADR-097 β federation peers (a Managed Agent session β a federated executor)+- ADR-026 β 3-tier model routing (Managed Agent `model` selection should route through this)+- ADR-112 β MCP tool discoverability (every new `*_agent_*({runtime:"managed"})` tool description must comply; must state the cost/beta caveats)+- #1916 β hive task-execution dispatch (Managed Agents as a third executor option)diff --git a/verification/inventory.json b/verification/inventory.jsonindex 94c8eeef15..6ab341eef9 100644--- a/verification/inventory.json+++ b/verification/inventory.json@@ -1955,10 +1955,10 @@"sourceFile": "plugins\\ruflo-testgen\\.claude-plugin\\plugin.json"},{- "name": "ruflo-wasm",+ "name": "ruflo-agent","version": "0.2.0","description": "Sandboxed WASM agent creation, execution, and gallery sharing β wraps 10 wasm_* MCP tools (agent_create/prompt/tool/list/terminate/files/export + gallery_list/search/create); built on @ruvector/rvagent-wasm + @ruvector/ruvllm-wasm per ADR-070 (Implemented)",- "sourceFile": "plugins\\ruflo-wasm\\.claude-plugin\\plugin.json"+ "sourceFile": "plugins\\ruflo-agent\\.claude-plugin\\plugin.json"},{"name": "ruflo-workflows",@@ -2217,8 +2217,8 @@{"name": "wasm-specialist","description": "WASM sandbox specialist for creating, managing, and sharing isolated agent environments",- "plugin": "ruflo-wasm",- "sourceFile": "plugins\\ruflo-wasm\\agents\\wasm-specialist.md"+ "plugin": "ruflo-agent",+ "sourceFile": "plugins\\ruflo-agent\\agents\\wasm-specialist.md"},{"name": "witness-auditor",