Agentic WAVS

.claude/skills/wavs/SKILL.md

@@ -40,13 +40,18 @@ just setup-claude-mcp [/path/to/project]
 just start-wavs-dev
 
 # 2. Run wavs-mcp (in a separate terminal)
-./target/release/wavs-mcp --wavs-url http://localhost:8000 --token <token>
+./target/release/wavs-mcp --wavs-url http://localhost:8000 --token <token> \
+  --exec-enabled \
+  --signing-mnemonic "word1 word2 ... word12" \
+  --mcp-chain-credential "0x<private-key>"
 
 # 3. Register with Claude Code
 npx @wavs/mcp@latest
 ```
 
-> **Local tools** (`scaffold_component`, `build_component`, `get_wit_interface`) work without MCP — useful for component development without a running node.
+> **Execution tools** (`wavs_exec_*`) require `--exec-enabled`. Tier 2 (`signed_result`) also needs `--signing-mnemonic`. Tier 3 (`on_chain`) also needs `--mcp-chain-credential` and `exec_enabled: true` in the service definition. See [`flows/execution.md`](flows/execution.md).
+
+> **Local tools** (`scaffold_component`, `build_component`, `validate_component`, `get_wit_interface`, `get_service_schema`) work without MCP — useful for component development without a running node.
 
 ---
 
@@ -57,6 +62,7 @@ npx @wavs/mcp@latest
 | Build a new component from scratch | [`flows/component-dev.md`](flows/component-dev.md) |
 | Deploy a new service with an on-chain contract | [`flows/deployment.md`](flows/deployment.md) |
 | Update a deployed service with a new component | [`flows/update-service.md`](flows/update-service.md) |
+| Execute a deployed service | [`flows/execution.md`](flows/execution.md) |
 
 When in doubt, start with **component-dev** — it ends with a deployment step.
 
@@ -68,9 +74,10 @@ When in doubt, start with **component-dev** — it ends with a deployment step.
 |----------|-------|---------------|
 | **Read** | `get_node_info`, `get_health`, `list_services`, `get_service` | None |
 | **Write** | `deploy_service`, `delete_service` | `--token` |
-| **Dev** | `upload_component`, `save_service`, `simulate_trigger`, `deploy_dev_service`, `query_kv` | Dev endpoints enabled |
-| **Chain-write** | `set_service_uri`, `deploy_service_manager`, `deploy_poa_service_manager`, `register_operator` | `WAVS_MCP_CHAIN_CREDENTIAL` env var |
-| **Local** | `get_wit_interface`, `scaffold_component`, `build_component` | None |
+| **Dev** | `upload_component`, `save_service`, `simulate_trigger`, `deploy_dev_service`, `query_kv`, `query_logs`, `query_component_logs` | Dev endpoints enabled |
+| **Chain-write** | `set_service_uri`, `deploy_service_manager`, `deploy_poa_service_manager`, `register_operator`, `deploy_and_register` | `WAVS_MCP_CHAIN_CREDENTIAL` env var |
+| **Local** | `get_service_schema`, `get_wit_interface`, `scaffold_component`, `build_component`, `validate_component` | None |
+| **Execution** | `wavs_exec_*` (dynamic, one per deployed workflow) | `--exec-enabled`; Tier 2 needs `--signing-mnemonic`; Tier 3 needs `--mcp-chain-credential` + `exec_enabled: true` |
 
 Full tool reference: [`reference/mcp-tools.md`](reference/mcp-tools.md)
 
@@ -90,12 +97,18 @@ The WAVS app "Register with Claude" button and `just setup-claude-mcp` write thi
 
 Dev endpoints must be enabled in `wavs.toml` under `[wavs]`:
 ```toml
-dev_endpoints_enabled = true   # Required for upload, save, simulate, deploy_dev
+dev_endpoints_enabled = true   # Required for upload, save, simulate, deploy_dev, query_logs
+```
+
+The `exec_enabled` field in a service definition controls Tier 3 (on-chain) execution:
+```json
+{ "exec_enabled": true }
 ```
+When omitted or `false`, only Tiers 1–2 are available for that service. See [`reference/service-json.md`](reference/service-json.md).
 
 ---
 
 ## Reference
 
-- [`reference/mcp-tools.md`](reference/mcp-tools.md) — All 20 tools with auth requirements and parameter notes
+- [`reference/mcp-tools.md`](reference/mcp-tools.md) — All 24+ tools with auth requirements and parameter notes (includes dynamic `wavs_exec_*`)
 - [`reference/service-json.md`](reference/service-json.md) — Service/trigger JSON formats + simulate examples

.claude/skills/wavs/flows/component-dev.md

@@ -6,13 +6,35 @@ Build, test, and deploy a new WAVS WASM component from scratch.
 
 ## Checklist
 
-- [ ] **Step 1** — `wavs:wavs_get_wit_interface` — Read WIT definitions to understand available APIs before writing code.
-- [ ] **Step 2** — `wavs:wavs_scaffold_component` — Generate project skeleton (`Cargo.toml` + `src/lib.rs`).
-- [ ] **Step 3** — Implement logic in `src/lib.rs` using the patterns below.
-- [ ] **Step 4** — `wavs:wavs_build_component` — Compile; read stderr and fix errors; repeat until exit code 0.
+- [ ] **Step 1** — `wavs:wavs_scaffold_component` with `dir` parameter — Creates the complete project on disk with all WIT files, bindings, and trigger template. Nothing to write manually.
+- [ ] **Step 2** — Customize `src/lib.rs` with your component logic.
+- [ ] **Step 3** — `wavs:wavs_build_component` — Compile; read stderr and fix errors; repeat until exit code 0.
+- [ ] **Step 4** — `wavs:wavs_validate_component` — Verify the .wasm exports the correct `run` function before uploading.
 - [ ] **Step 5** — `wavs:wavs_upload_component` — Upload `.wasm`; save the returned digest (raw 64-char hex, no `sha256:` prefix).
+  - **OCI alternative:** If the component is published to an OCI registry (e.g. ghcr.io), you can skip upload and use an OCI source in the service definition instead: `"source": {"oci": {"uri": "oci://ghcr.io/org/component:v1.0"}}`. See [`reference/service-json.md`](../reference/service-json.md#oci-pull-from-registry-at-deploy-time) for details.
 - [ ] **Step 6** — `wavs:wavs_deploy_dev_service` (no on-chain contract) **or** follow [`deployment.md`](deployment.md) for a real deployment.
-- [ ] **Step 7** — `wavs:wavs_simulate_trigger` — Verify output.
+- [ ] **Step 7** — If the `ui_navigate` tool is available (WAVS desktop app embedded agent only), **immediately** call it to open the service detail page (path from deploy output). Don't wait — navigate right after deploy so the user can see the service.
+- [ ] **Step 8** — `wavs:wavs_simulate_trigger` — Verify output.
+
+> **Tip:** Call `wavs:wavs_get_wit_interface` if you need to understand the full WIT API (HTTP, KV, host functions, etc.) before writing custom logic.
+> **Tip:** Omit the `dir` parameter from `wavs_scaffold_component` to get file contents as text instead of writing to disk (useful when integrating into existing projects).
+
+---
+
+## How Scaffolding Works
+
+**With `dir` parameter (recommended):** The tool creates `{dir}/{name}/` with all files ready to build. No manual file creation needed.
+
+**Without `dir`:** Returns file contents as text. You must write every file yourself, including the `wit/` directory. Use this only when integrating into an existing project.
+
+The scaffolded project is self-contained:
+- Builds with `cargo build --target wasm32-wasip2 --release` (no `cargo-component` needed)
+- All WIT interface definitions are bundled in `wit/`
+- **Prerequisite:** `rustup target add wasm32-wasip2`
+
+### In-Workspace Alternative (WAVS repo only)
+
+If working inside the WAVS monorepo, you can instead create a component at `examples/components/{name}/` using `example-helpers = { workspace = true }`. This is simpler (only 2 files, no WIT copy needed) but only works within the workspace. Build with `cargo component build --release -p {name}`.
 
 ---
 
@@ -24,11 +46,9 @@ trigger_type: evm_contract_event | cosmos_contract_event | block_interval | cron
 description:  optional one-line description
 ```
 
-Place the generated component at `examples/components/{name}/` to use workspace deps automatically.
-
 ---
 
-## Component Anatomy
+## Component Anatomy (In-Workspace)
 
 Minimal working component using the prelude:
 
@@ -40,23 +60,24 @@ struct Component;
 
 impl Guest for Component {
     fn run(action: TriggerAction) -> Result<Vec<WasmResponse>, String> {
-        let (trigger_id, data) = decode_trigger_event(action.data)?;
-
-        // Process `data` bytes and compute output.
-        let output = data; // echo the raw input for now
-
-        Ok(vec![encode_trigger_output(
-            trigger_id,
-            &output,
-            action.config.service_id,
-        )])
+        match action.data {
+            TriggerData::Raw(data) => {
+                // Process raw input bytes
+                Ok(vec![WasmResponse {
+                    payload: data,
+                    ordering: None,
+                    event_id_salt: None,
+                }])
+            }
+            _ => Err("Unsupported trigger data type".to_string()),
+        }
     }
 }
 
 export_layer_trigger_world!(Component);
 ```
 
-The prelude re-exports: `Guest`, `TriggerAction`, `WasmResponse`, `decode_trigger_event`, `encode_trigger_output`, `export_layer_trigger_world`, and the `host` module.
+The prelude re-exports: `Guest`, `TriggerAction`, `TriggerData`, `Trigger`, `WasmResponse`, `decode_trigger_event`, `encode_trigger_output`, `export_layer_trigger_world`, and the `host` module.
 
 Full explicit imports (when you need specific types):
 
@@ -73,11 +94,60 @@ use example_helpers::export_layer_trigger_world;
 use example_helpers::trigger::{decode_trigger_event, encode_trigger_output};
 ```
 
+## Component Anatomy (Standalone)
+
+```rust
+#[allow(warnings)]
+mod bindings;
+
+use crate::bindings::{
+    export,
+    wavs::types::events::TriggerData,
+    Guest, TriggerAction, WasmResponse,
+};
+
+struct Component;
+export!(Component with_types_in bindings);
+
+impl Guest for Component {
+    fn run(action: TriggerAction) -> std::result::Result<Vec<WasmResponse>, String> {
+        match action.data {
+            TriggerData::Raw(data) => {
+                let payload = data; // echo input back
+                Ok(vec![WasmResponse {
+                    payload,
+                    ordering: None,
+                    event_id_salt: None,
+                }])
+            }
+            _ => Err("Unsupported trigger data type".to_string()),
+        }
+    }
+}
+```
+
+With `src/bindings.rs`:
+```rust
+#[allow(warnings)]
+mod _inner {
+    wit_bindgen::generate!({
+        world: "wavs-world",
+        path: "wit",
+        pub_export_macro: true,
+        generate_all,
+        features: ["tls"],
+    });
+}
+pub use _inner::*;
+```
+
 ---
 
 ## Host APIs
 
 ```rust
+// In-workspace: available via `host::` directly
+// Standalone: use `crate::bindings::host`
 host::config_var("my-key")               // → Option<String>; reads service config
 host::log(host::LogLevel::Info, "msg");  // levels: Debug, Info, Warn, Error
 host::get_service()                      // → ServiceInfo (manager address, config, etc.)
@@ -91,18 +161,26 @@ host::get_event_id(Some(salt))           // custom salt (Vec<u8>)
 
 ```rust
 match action.data {
-    TriggerData::EvmContractEvent(_) | TriggerData::CosmosContractEvent(_) => {
-        let (trigger_id, data) = decode_trigger_event(action.data)?;
+    TriggerData::EvmContractEvent(event_data) => {
+        // event_data.chain: chain key string
+        // event_data.log.data.data: raw ABI-encoded log bytes
+        // event_data.log.data.topics: Vec of topic byte arrays
+    }
+    TriggerData::CosmosContractEvent(event_data) => {
+        // event_data.chain: chain key string
+        // event_data.event.ty: event type string
+        // event_data.event.attributes: Vec<(String, String)>
+        // event_data.block_height: u64
     }
     TriggerData::Raw(bytes) => {
-        // Plain bytes — trigger_id is 0 for raw/manual triggers.
-        let data = bytes;
+        // Plain bytes — for manual/raw triggers
     }
-    TriggerData::Cron { trigger_time } => {
-        // trigger_time: unix timestamp (u64)
+    TriggerData::Cron(data) => {
+        // data.trigger_time.nanos: unix timestamp in nanoseconds
     }
-    TriggerData::BlockInterval { block_height } => {
-        // block_height: u64
+    TriggerData::BlockInterval(data) => {
+        // data.block_height: u64
+        // data.chain: chain key string
     }
     _ => return Err("unsupported trigger type".to_string()),
 }
@@ -116,6 +194,7 @@ match action.data {
 
 ```rust
 use example_helpers::bindings::world::wasi::keyvalue::{store, atomics};
+// Standalone: use crate::bindings::wasi::keyvalue::{store, atomics};
 
 let bucket = store::open("my-bucket").map_err(|e| e.to_string())?;
 let value: Option<Vec<u8>> = bucket.get("key").map_err(|e| e.to_string())?;
@@ -139,38 +218,47 @@ let bytes = block_on(async {
 
 ---
 
-## Cargo.toml Template
+## Cargo.toml Template (In-Workspace)
 
 Place at `examples/components/{name}/Cargo.toml`:
 
 ```toml
 [package]
 name = "{name}"
 edition.workspace = true
+version.workspace = true
+authors.workspace = true
+rust-version.workspace = true
+repository.workspace = true
 
 [lib]
 crate-type = ["cdylib"]
 
 [package.metadata.component]
-package = "wavs-user:{name}"
+package = "component:{name}"
 
 [dependencies]
-example-helpers = { path = "../../_helpers" }
-serde = { version = "1", features = ["derive"] }
-serde_json = "1"
-# Add for KV store or outbound HTTP:
+example-helpers = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+# Uncomment for async HTTP, timers, etc:
 # wstd = { workspace = true }
 ```
 
 ---
 
 ## Build Output Paths
 
-After `wavs_build_component` (release mode):
+After `wavs_build_component` or `cargo component build --release` (workspace):
 ```
 target/wasm32-wasip1/release/{package_name_with_underscores}.wasm
 ```
 
+After `cargo build --target wasm32-wasip2 --release` (standalone):
+```
+target/wasm32-wasip2/release/{package_name_with_underscores}.wasm
+```
+
 After `just wasi-build-native {component-name}` (from repo root):
 ```
 examples/build/components/{component-name}.wasm
@@ -183,13 +271,17 @@ Use the **absolute path** when calling `wavs_upload_component`.
 ## Debugging
 
 **Build errors** (read `stderr` from `wavs_build_component`):
-- `cannot find type` / `unresolved import` — check `example-helpers` path; try `use example_helpers::prelude::*`
+- `cannot find type` / `unresolved import` — check import paths match your scaffold mode (workspace vs standalone)
+- `failed to create a target world` / `package not found` — WIT files are missing. For standalone: ensure all `wit/deps/*/package.wit` files are written. For workspace: ensure `example-helpers` path is correct.
 - `the trait bound is not satisfied` — `encode_trigger_output` needs `&[u8]` or `AsRef<[u8]>`
-- `does not implement Guest` — ensure `export_layer_trigger_world!(Component)` is present
+- `does not implement Guest` — ensure export macro is present (`export_layer_trigger_world!` for workspace, `export!` for standalone)
+- `no export 'run' found` — the export macro is missing or the `Guest` impl is not correct
 
 **Runtime errors** (from `wavs_simulate_trigger`):
 - Error message comes directly from your `?` or `return Err(...)` calls
 - Add `host::log(host::LogLevel::Debug, &format!("data: {:?}", data))` and re-simulate
+- Use `wavs_query_component_logs(service_id="<id>", level="debug")` to read component `host::log()` output after simulation
+- Use `wavs_query_logs(target="wavs::subsystems::engine", level="warn")` for broader engine-level diagnostics
 
 **Missing config vars** — component returns `"config var X not found"`:
 - Service definition must include the key in its `config` map

.claude/skills/wavs/flows/deployment.md

@@ -18,13 +18,16 @@ Deploy a new WAVS service with an on-chain ServiceManager contract.
   - **SimpleServiceManager** (lightweight PoA): `wavs:wavs_deploy_service_manager` — returns `address`
   - **POAStakeRegistry** (full middleware): `wavs:wavs_deploy_poa_service_manager` — returns proxy `address`; requires Docker
 - [ ] **Step 3** — `wavs:wavs_upload_component` — Upload the compiled `.wasm`; save the returned digest (raw 64-char hex, no `sha256:` prefix).
+  - **OCI alternative:** If the component is published to an OCI registry, skip upload and use `"source": {"oci": {"uri": "oci://ghcr.io/org/component:v1.0"}}` in the service definition. The WAVS node pulls it at deploy time. See [`reference/service-json.md`](../reference/service-json.md#oci-pull-from-registry-at-deploy-time).
 - [ ] **Step 4** — `wavs:wavs_save_service` — Save the service definition JSON; get back a URI.
 - [ ] **Step 5** — `wavs:wavs_set_service_uri` — Call `setServiceURI` on-chain with the URI from step 4.
 - [ ] **Step 6** — `wavs:wavs_deploy_service` — Register the service with the WAVS node (reads definition from chain).
   - **Verify the node picked up the service:** Call `wavs:wavs_get_service(chain, address)` and confirm `status: active`. Note: `wavs_deploy_service` returning success only means the node fetched and stored the config from the on-chain URI. Confirm active status with `wavs_get_service`.
+  - If the `ui_navigate` tool is available (WAVS desktop app embedded agent only), **immediately** call it to open the service detail page (use the path from the deploy output). Don't wait — navigate right after deploy so the user can see the service.
 - [ ] **Step 7 (POA only)** — `wavs:wavs_register_operator` — Register the node's signing key on the POAStakeRegistry. **Must be called AFTER `wavs_deploy_service`** so the node has assigned a service-specific HD-derived signing key to register on-chain.
 - [ ] **Step 8** — `wavs:wavs_simulate_trigger` — Smoke test.
 - [ ] **Step 9** — `wavs:wavs_list_services` — Confirm the service appears with `status: active`.
+- [ ] **Step 10 (optional)** — If `--exec-enabled` is set on the MCP server, the service is now available as a `wavs_exec_*` tool. Follow [`flows/execution.md`](execution.md) to execute it at any trust tier.
 
 ---
 
@@ -86,6 +89,7 @@ Pass to `wavs_save_service` or `wavs_deploy_dev_service`:
 {
   "name": "my-service",
   "status": "active",
+  "exec_enabled": true,
   "manager": {
     "evm": {
       "chain": "evm:31337",