update docs and skills

Author: codeitlikemiley

ARCHITECTURE.md

@@ -41,7 +41,7 @@ The SDK leverages several object-oriented and functional design patterns:
   - `post_tool_call()`
   - `on_tool_error()`
   - `on_interaction()`
-- **HookRunner**: Coordinates a thread-safe list of observers (`Arc<dyn Hook>`) and dispatches events asynchronously.
+- **HookRunner**: Coordinates a thread-safe list of observers (`Arc<dyn DynHook>`) and dispatches events asynchronously.
 
 ### 3. Middleware / Interceptor Pattern (`policy.rs`)
 - **Policy**: Acts as a middleware layer to authorize, deny, or intercept tool calls before they are executed.
@@ -139,7 +139,7 @@ Standard native runtimes run on multi-threaded thread pools. In contrast, WASM r
 The SDK has been fully refactored to leverage native async traits (stable since Rust 1.75 / Rust 2024), completely removing the dependency on the `#[async_trait]` macro.
 
 - **Native Async Traits**: Traits like `Connection`, `Hook`, `Tool`, and `Trigger` are implemented as native async traits using standard `async fn` syntax or returning `impl Future + Send` to ensure compiler-enforced thread safety boundaries.
-- **Companion Trait Pattern for Dynamic Dispatch**: Native async traits are not directly object-safe (`dyn Trait` compatible) because they return anonymous concrete futures. To support dynamic dispatch, the SDK defines companion traits `DynConnection`, `DynHook`, `DynTool`, and `DynTrigger` which are object-safe and return boxed futures (`BoxFuture`).
+- **Companion Trait Pattern for Dynamic Dispatch**: Native async traits are not directly object-safe (`dyn Trait` compatible) because they return anonymous concrete futures. To support dynamic dispatch, the SDK defines companion traits `DynHook`, `DynTool`, and `DynTrigger` which are object-safe and return boxed futures (`BoxFuture`).
 - **Zero-overhead Blanket Implementations**: The companion traits are automatically implemented via blanket implementations for any type implementing the base trait:
   ```rust
   pub trait DynHook: Send + Sync {
@@ -154,4 +154,4 @@ The SDK has been fully refactored to leverage native async traits (stable since
       // ...
   }
   ```
-  This provides the best of both worlds: clean, idiomatic implementation of async traits for developers using standard Rust 2024 features, while preserving the internal ability to handle collections of dynamic trait objects (e.g. `Arc<dyn DynHook>` in `HookRunner`, `Box<dyn DynTool>` in `ToolRunner`, `AnyConnection` enum dispatch, etc.).
+  This provides the best of both worlds: clean, idiomatic implementation of async traits for developers using standard Rust 2024 features, while preserving the internal ability to handle collections of dynamic trait objects (e.g. `Arc<dyn DynHook>` in `HookRunner`, `Arc<dyn DynTool>` in `ToolRunner`, `AnyConnection` enum dispatch, etc.).

README.md

@@ -139,11 +139,9 @@ impl Tool for WeatherTool {
         }"#
     }
 
-    fn call(&self, args: Value) -> impl std::future::Future<Output = Result<Value, anyhow::Error>> + Send {
-        async move {
-            let city = args.get("city").and_then(|c| c.as_str()).unwrap_or("Tokyo");
-            Ok(serde_json::json!({ "weather": format!("It's sunny in {}", city) }))
-        }
+    async fn call(&self, args: Value) -> Result<Value, anyhow::Error> {
+        let city = args.get("city").and_then(|c| c.as_str()).unwrap_or("Tokyo");
+        Ok(serde_json::json!({ "weather": format!("It's sunny in {}", city) }))
     }
 }
 ```

skills/google-antigravity-sdk-rust/SKILL.md

@@ -23,6 +23,24 @@ Ensure the following prerequisites are met before building or running agents:
 
 ---
 
+## WebAssembly (wasm32-wasip1) Target Guidelines
+
+When designing and deploying agents to WebAssembly targets such as `wasm32-wasip1` (e.g., inside Spin or standard WASI runtimes):
+
+1. **Compilation Check**: Always verify clean target compilation:
+   ```sh
+   cargo check --target wasm32-wasip1
+   ```
+2. **Connection Protocol**: Be aware that process spawning is not supported inside WebAssembly sandboxes. Instead of native subprocess IPC, use the direct network socket strategy (`WasmConnectionStrategy` / `WasmConnection`) to connect to a host-side `localharness` WebSocket server.
+3. **Core Async Traits**: Do NOT use the `#[async_trait]` attribute macro. The SDK uses native async traits (stable since Rust 1.75 / Rust 2024). Standard traits like `Connection`, `Hook`, `Tool`, and `Trigger` are implemented as native async traits (using `impl Future + Send` returns for trait-level `Send` bounds). For dynamic dispatch and runtime storage (e.g. `Arc<dyn DynHook>`), the SDK provides companion object-safe traits (`DynHook`, `DynTool`, `DynTrigger`) which are automatically implemented via blanket implementations for any type implementing the base trait.
+4. **Mock Test Suite Guidelines**: To test connection, event loops, and tool extractions under simulated WebSocket messaging, run:
+   ```sh
+   cargo test wasm::tests
+   ```
+   * **Writing Mock Tests**: Mock tests should spin up a local WebSocket listener, bind to port `0` to allocate a free TCP port dynamically, record that port, configure `WasmConnectionStrategy` to point to it, and mock standard JSON frames (`StepUpdate`, `TrajectoryStateUpdate`, etc.) to verify client state transitions.
+
+---
+
 ## Routing Table
 
 Use the links below to navigate specific topics and code configurations:
@@ -72,3 +90,5 @@ Use the links below to navigate specific topics and code configurations:
   See [agent_skills.md](file:///Volumes/goldcoders/antigravity-sdk-rust/skills/google-antigravity-sdk-rust/examples/getting_started/agent_skills.md).
 * **Policies**: Lock workspace directories and filter command lines.
   See [policies.md](file:///Volumes/goldcoders/antigravity-sdk-rust/skills/google-antigravity-sdk-rust/examples/getting_started/policies.md).
+* **Streaming**: Stream chat responses and distinguish reasoning thoughts from response text in real time.
+  See [streaming.md](file:///Volumes/goldcoders/antigravity-sdk-rust/skills/google-antigravity-sdk-rust/examples/getting_started/streaming.md).

skills/google-antigravity-sdk-rust/examples/getting_started/custom_tool.md

@@ -11,14 +11,12 @@ use antigravity_sdk_rust::agent::{Agent, AgentConfig};
 use antigravity_sdk_rust::policy;
 use antigravity_sdk_rust::tools::Tool;
 use antigravity_sdk_rust::types::GeminiConfig;
-use async_trait::async_trait;
 use serde_json::Value;
 use std::sync::Arc;
 
 // 1. Define the custom tool struct
 pub struct WeatherTool;
 
-#[async_trait]
 impl Tool for WeatherTool {
     fn name(&self) -> &str {
         "get_current_temperature"
@@ -41,15 +39,17 @@ impl Tool for WeatherTool {
         }"#
     }
 
-    async fn call(&self, args: Value) -> Result<Value, anyhow::Error> {
-        let location = args
-            .get("location")
-            .and_then(Value::as_str)
-            .ok_or_else(|| anyhow::anyhow!("Missing 'location' parameter"))?;
-        
-        // In a real application, call an external weather API here
-        let temperature = format!("The temperature in {} is 72°F.", location);
-        Ok(Value::String(temperature))
+    fn call(&self, args: Value) -> impl std::future::Future<Output = Result<Value, anyhow::Error>> + Send {
+        async move {
+            let location = args
+                .get("location")
+                .and_then(Value::as_str)
+                .ok_or_else(|| anyhow::anyhow!("Missing 'location' parameter"))?;
+            
+            // In a real application, call an external weather API here
+            let temperature = format!("The temperature in {} is 72°F.", location);
+            Ok(Value::String(temperature))
+        }
     }
 }
 
@@ -86,7 +86,6 @@ Here is how to implement a stateful fruit count tracker tool:
 use antigravity_sdk_rust::agent::{Agent, AgentConfig};
 use antigravity_sdk_rust::policy;
 use antigravity_sdk_rust::tools::Tool;
-use async_trait::async_trait;
 use serde_json::Value;
 use std::collections::HashMap;
 use std::sync::{Arc, Mutex};
@@ -104,7 +103,6 @@ impl FruitInventoryTool {
     }
 }
 
-#[async_trait]
 impl Tool for FruitInventoryTool {
     fn name(&self) -> &str {
         "record_fruit"
@@ -131,28 +129,30 @@ impl Tool for FruitInventoryTool {
         }"#
     }
 
-    async fn call(&self, args: Value) -> Result<Value, anyhow::Error> {
-        let fruit_name = args
-            .get("fruit_name")
-            .and_then(Value::as_str)
-            .ok_or_else(|| anyhow::anyhow!("Missing 'fruit_name'"))?;
-        let count = args
-            .get("count")
-            .and_then(Value::as_i64)
-            .ok_or_else(|| anyhow::anyhow!("Missing 'count'"))? as i32;
-
-        let mut inv = self
-            .inventory
-            .lock()
-            .map_err(|e| anyhow::anyhow!("Mutex lock poisoned: {}", e))?;
-        let entry = inv.entry(fruit_name.to_string()).or_insert(0);
-        *entry += count;
-
-        let result_msg = format!(
-            "Recorded {} {}(s). Total {} count is now {}.",
-            count, fruit_name, fruit_name, *entry
-        );
-        Ok(Value::String(result_msg))
+    fn call(&self, args: Value) -> impl std::future::Future<Output = Result<Value, anyhow::Error>> + Send {
+        async move {
+            let fruit_name = args
+                .get("fruit_name")
+                .and_then(Value::as_str)
+                .ok_or_else(|| anyhow::anyhow!("Missing 'fruit_name'"))?;
+            let count = args
+                .get("count")
+                .and_then(Value::as_i64)
+                .ok_or_else(|| anyhow::anyhow!("Missing 'count'"))? as i32;
+
+            let mut inv = self
+                .inventory
+                .lock()
+                .map_err(|e| anyhow::anyhow!("Mutex lock poisoned: {}", e))?;
+            let entry = inv.entry(fruit_name.to_string()).or_insert(0);
+            *entry += count;
+
+            let result_msg = format!(
+                "Recorded {} {}(s). Total {} count is now {}.",
+                count, fruit_name, fruit_name, *entry
+            );
+            Ok(Value::String(result_msg))
+        }
     }
 }
 

skills/google-antigravity-sdk-rust/examples/getting_started/hooks.md

@@ -9,59 +9,63 @@ To create custom hooks, implement the `Hook` trait:
 ```rust
 use antigravity_sdk_rust::hooks::Hook;
 use antigravity_sdk_rust::types::{AskQuestionEntry, HookResult, QuestionHookResult, ToolCall, ToolResult};
-use async_trait::async_trait;
 
-#[async_trait]
 pub trait Hook: Send + Sync {
     /// Triggered when the agent establishes a connection and starts a session.
-    async fn on_session_start(&self) -> Result<(), anyhow::Error> {
-        Ok(())
+    fn on_session_start(&self) -> impl std::future::Future<Output = Result<(), anyhow::Error>> + Send {
+        async { Ok(()) }
     }
 
     /// Intercepts the start of a user turn before the LLM processes the prompt.
     /// Returns `allow: false` to halt execution.
-    async fn pre_turn(&self) -> Result<HookResult, anyhow::Error> {
-        Ok(HookResult {
-            allow: true,
-            message: String::new(),
-        })
+    fn pre_turn(&self) -> impl std::future::Future<Output = Result<HookResult, anyhow::Error>> + Send {
+        async {
+            Ok(HookResult {
+                allow: true,
+                message: String::new(),
+            })
+        }
     }
 
     /// Intercepts a tool call immediately before it is executed by the runner.
     /// Returns `allow: false` to prevent execution.
-    async fn pre_tool_call(&self, _tool_call: &ToolCall) -> Result<HookResult, anyhow::Error> {
-        Ok(HookResult {
-            allow: true,
-            message: String::new(),
-        })
+    fn pre_tool_call<'a>(&'a self, _tool_call: &'a ToolCall) -> impl std::future::Future<Output = Result<HookResult, anyhow::Error>> + Send {
+        async {
+            Ok(HookResult {
+                allow: true,
+                message: String::new(),
+            })
+        }
     }
 
     /// Triggered after a tool successfully returns a result.
-    async fn post_tool_call(&self, _result: &ToolResult) -> Result<(), anyhow::Error> {
-        Ok(())
+    fn post_tool_call<'a>(&'a self, _result: &'a ToolResult) -> impl std::future::Future<Output = Result<(), anyhow::Error>> + Send {
+        async { Ok(()) }
     }
 
     /// Triggered when a tool execution encounters an error.
     /// Allows fallback logic or customized error payloads.
-    async fn on_tool_error(
-        &self,
-        error: &anyhow::Error,
-    ) -> Result<(HookResult, Option<serde_json::Value>), anyhow::Error> {
-        Ok((
-            HookResult {
-                allow: false,
-                message: error.to_string(),
-            },
-            None,
-        ))
+    fn on_tool_error<'a>(
+        &'a self,
+        error: &'a anyhow::Error,
+    ) -> impl std::future::Future<Output = Result<(HookResult, Option<serde_json::Value>), anyhow::Error>> + Send {
+        async move {
+            Ok((
+                HookResult {
+                    allow: false,
+                    message: error.to_string(),
+                },
+                None,
+            ))
+        }
     }
 
     /// Intercepts a prompt to ask the user clarifying questions.
-    async fn on_interaction(
-        &self,
-        _questions: &[AskQuestionEntry],
-    ) -> Result<Option<QuestionHookResult>, anyhow::Error> {
-        Ok(None)
+    fn on_interaction<'a>(
+        &'a self,
+        _questions: &'a [AskQuestionEntry],
+    ) -> impl std::future::Future<Output = Result<Option<QuestionHookResult>, anyhow::Error>> + Send {
+        async { Ok(None) }
     }
 }
 ```
@@ -77,38 +81,44 @@ use antigravity_sdk_rust::agent::{Agent, AgentConfig};
 use antigravity_sdk_rust::hooks::Hook;
 use antigravity_sdk_rust::policy;
 use antigravity_sdk_rust::types::{HookResult, ToolCall, ToolResult};
-use async_trait::async_trait;
 use std::sync::Arc;
 
 // 1. Define custom hook struct
 struct LoggerHook;
 
-#[async_trait]
 impl Hook for LoggerHook {
-    async fn on_session_start(&self) -> Result<(), anyhow::Error> {
-        println!("[Hook] Session has successfully started!");
-        Ok(())
+    fn on_session_start(&self) -> impl std::future::Future<Output = Result<(), anyhow::Error>> + Send {
+        async {
+            println!("[Hook] Session has successfully started!");
+            Ok(())
+        }
     }
 
-    async fn pre_turn(&self) -> Result<HookResult, anyhow::Error> {
-        println!("[Hook] Preparing next turn...");
-        Ok(HookResult {
-            allow: true,
-            message: String::new(),
-        })
+    fn pre_turn(&self) -> impl std::future::Future<Output = Result<HookResult, anyhow::Error>> + Send {
+        async {
+            println!("[Hook] Preparing next turn...");
+            Ok(HookResult {
+                allow: true,
+                message: String::new(),
+            })
+        }
     }
 
-    async fn pre_tool_call(&self, tool_call: &ToolCall) -> Result<HookResult, anyhow::Error> {
-        println!("[Hook] Inspecting tool call request: {}", tool_call.name);
-        Ok(HookResult {
-            allow: true,
-            message: String::new(),
-        })
+    fn pre_tool_call<'a>(&'a self, tool_call: &'a ToolCall) -> impl std::future::Future<Output = Result<HookResult, anyhow::Error>> + Send {
+        async move {
+            println!("[Hook] Inspecting tool call request: {}", tool_call.name);
+            Ok(HookResult {
+                allow: true,
+                message: String::new(),
+            })
+        }
     }
 
-    async fn post_tool_call(&self, result: &ToolResult) -> Result<(), anyhow::Error> {
-        println!("[Hook] Tool call completed with result: {:?}", result.result);
-        Ok(())
+    fn post_tool_call<'a>(&'a self, result: &'a ToolResult) -> impl std::future::Future<Output = Result<(), anyhow::Error>> + Send {
+        async move {
+            println!("[Hook] Tool call completed with result: {:?}", result.result);
+            Ok(())
+        }
     }
 }
 

skills/google-antigravity-sdk-rust/examples/getting_started/multimodal.md

@@ -9,8 +9,7 @@ To enable the agent to generate images on request, you must add `BuiltinTools::G
 ```rust
 use antigravity_sdk_rust::agent::{Agent, AgentConfig};
 use antigravity_sdk_rust::policy;
-use antigravity_sdk_rust::types::{BuiltinTools, CapabilitiesConfig, GeminiConfig};
-use std::sync::Arc;
+use antigravity_sdk_rust::types::{BuiltinTools, CapabilitiesConfig};
 
 #[tokio::main]
 async fn main() -> Result<(), anyhow::Error> {