update docs

Author: codeitlikemiley

ARCHITECTURE.md

@@ -11,12 +11,15 @@ The Antigravity SDK orchestrates interactions between an LLM-based agent (runnin
 ```mermaid
 graph TD
     A[Agent] --> B[Conversation]
-    A --> C[LocalConnection]
+    A --> C[LocalConnection / WasmConnection]
     A --> D[ToolRunner]
     A --> E[HookRunner]
+    A --> I[TriggerRunner]
     C -->|Subprocess IPC / WebSocket| F[localharness]
+    C -->|Network WebSocket| F
     D -->|Executes| G[Local Tools]
     E -->|Intercepts| H[User Hooks / Policies]
+    I -->|Spawns| J[Background Triggers]
 ```
 
 ---
@@ -25,9 +28,10 @@ graph TD
 
 The SDK leverages several object-oriented and functional design patterns:
 
-### 1. Connection & Strategy Pattern (`connection.rs`, `local.rs`)
-- **Connection Trait**: Defines an abstraction for communication. This allows swapping the local subprocess harness with other backends (e.g., remote or mock harnesses) in the future.
-- **LocalConnectionStrategy**: Acts as a builder/strategy to configure and initialize a `LocalConnection`.
+### 1. Connection & Strategy Pattern (`connection.rs`, `local.rs`, `wasm.rs`)
+- **Connection Trait**: Defines an abstraction for communication. This allows swapping the local subprocess harness with other backends (e.g., remote, mock, or WASM-based network harnesses) in the future.
+- **LocalConnectionStrategy**: Configures and initializes a `LocalConnection` by spawning a local helper subprocess (for native / non-WASM environments).
+- **WasmConnectionStrategy**: Configures and initializes a `WasmConnection` that connects to a remote or host-side `localharness` WebSocket server over TCP (enabled for `target_arch = "wasm32"` environments where subprocess spawning is not supported).
 
 ### 2. Observer Pattern (`hooks.rs`)
 - **Hook Trait**: Defines lifecycle hooks that users can register to observe and modify agent actions:
@@ -49,13 +53,20 @@ The SDK leverages several object-oriented and functional design patterns:
 - **Tool Trait**: Encapsulates specific capabilities (e.g., file edits, command execution, directory searching) into unified command units.
 - **ToolRunner**: Coordinates registration and execution of these command objects, mapping harness tool calls to their respective handlers.
 
+### 5. Background Trigger Pattern (`triggers.rs`)
+- **Trigger Trait**: Defines asynchronous background tasks (such as status polling, listener intervals, etc.) that can interact with the connection session concurrently.
+- **TriggerRunner**: Coordinates and spawns registered triggers in separate tasks when the agent session starts.
+
+### 6. Direct Gemini Client (`direct.rs`)
+- **GeminiDirectClient**: A transport-agnostic client that constructs REST request payloads and parses responses directly from the Gemini API. Bypasses the `localharness` and WebSocket loop entirely. It is helpful for environments where TCP/WebSocket or spawning subprocesses is not possible (e.g. lightweight WASI components).
+
 ---
 
 ## Component Details
 
-### Connection Lifecycle
+### Connection Lifecycle (Native Subprocess)
 
-The connection to `localharness` follows a strict handshake and upgrade protocol:
+The connection to `localharness` via subprocess follows a strict handshake and upgrade protocol:
 
 ```mermaid
 sequenceDiagram
@@ -79,6 +90,21 @@ sequenceDiagram
 3. **Upgrade**: The SDK initiates a WebSocket client connection to the harness server using the retrieved port and API key, upgrading communication to a structured bi-directional stream.
 4. **Disconnection**: When dropped, the subprocess is killed cleanly.
 
+### Connection Lifecycle (WebAssembly Network Target)
+
+For WebAssembly targets (`wasm32-wasip1`), the SDK connects to a running host-side harness over the network rather than spawning a subprocess:
+
+```mermaid
+sequenceDiagram
+    participant SDK as WASM Rust SDK
+    participant Host as Host Machine (localharness)
+
+    SDK->>Host: Open TCP Connection & Upgrade to WebSocket (with API Key)
+    Host->>SDK: Handshake Completed
+    SDK->>Host: Send InitializeConversationEvent (HarnessConfig)
+    Note over SDK,Host: Step execution loop active
+```
+
 ---
 
 ## Thread Safety & Concurrency

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

@@ -9,43 +9,47 @@ In the Rust SDK, custom tools are defined by implementing the `Tool` trait. You
 ```rust
 use antigravity_sdk_rust::agent::{Agent, AgentConfig};
 use antigravity_sdk_rust::policy;
-use antigravity_sdk_rust::tool::Tool;
+use antigravity_sdk_rust::tools::Tool;
 use antigravity_sdk_rust::types::GeminiConfig;
 use async_trait::async_trait;
-use serde_json::json;
+use serde_json::Value;
 use std::sync::Arc;
 
 // 1. Define the custom tool struct
 pub struct WeatherTool;
 
 #[async_trait]
 impl Tool for WeatherTool {
-    fn declaration(&self) -> serde_json::Value {
-        // Return JSON Schema outlining name, description, and parameters
-        json!({
-            "name": "get_current_temperature",
-            "description": "Gets the current temperature for a given location.",
-            "parameters": {
-                "type": "OBJECT",
-                "properties": {
-                    "location": {
-                        "type": "STRING",
-                        "description": "The city and state, e.g. 'San Francisco, CA'"
-                    }
-                },
-                "required": ["location"]
-            }
-        })
+    fn name(&self) -> &str {
+        "get_current_temperature"
+    }
+
+    fn description(&self) -> &str {
+        "Gets the current temperature for a given location."
+    }
+
+    fn parameters_json_schema(&self) -> &str {
+        r#"{
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "description": "The city and state, e.g. 'San Francisco, CA'"
+                }
+            },
+            "required": ["location"]
+        }"#
     }
 
-    async fn call(&self, args: serde_json::Value) -> Result<serde_json::Value, anyhow::Error> {
-        let location = args["location"]
-            .as_str()
+    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(json!({ "result": temperature }))
+        Ok(Value::String(temperature))
     }
 }
 
@@ -81,9 +85,9 @@ Here is how to implement a stateful fruit count tracker tool:
 ```rust
 use antigravity_sdk_rust::agent::{Agent, AgentConfig};
 use antigravity_sdk_rust::policy;
-use antigravity_sdk_rust::tool::Tool;
+use antigravity_sdk_rust::tools::Tool;
 use async_trait::async_trait;
-use serde_json::json;
+use serde_json::Value;
 use std::collections::HashMap;
 use std::sync::{Arc, Mutex};
 
@@ -102,44 +106,53 @@ impl FruitInventoryTool {
 
 #[async_trait]
 impl Tool for FruitInventoryTool {
-    fn declaration(&self) -> serde_json::Value {
-        json!({
-            "name": "record_fruit",
-            "description": "Records the mention of fruits and updates the total count.",
-            "parameters": {
-                "type": "OBJECT",
-                "properties": {
-                    "fruit_name": {
-                        "type": "STRING",
-                        "description": "The name of the fruit."
-                    },
-                    "count": {
-                        "type": "INTEGER",
-                        "description": "The number of fruits mentioned."
-                    }
+    fn name(&self) -> &str {
+        "record_fruit"
+    }
+
+    fn description(&self) -> &str {
+        "Records the mention of fruits and updates the total count."
+    }
+
+    fn parameters_json_schema(&self) -> &str {
+        r#"{
+            "type": "object",
+            "properties": {
+                "fruit_name": {
+                    "type": "string",
+                    "description": "The name of the fruit."
                 },
-                "required": ["fruit_name", "count"]
-            }
-        })
+                "count": {
+                    "type": "integer",
+                    "description": "The number of fruits mentioned."
+                }
+            },
+            "required": ["fruit_name", "count"]
+        }"#
     }
 
-    async fn call(&self, args: serde_json::Value) -> Result<serde_json::Value, anyhow::Error> {
-        let fruit_name = args["fruit_name"]
-            .as_str()
+    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["count"]
-            .as_i64()
+        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().unwrap();
+        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(json!({ "result": result_msg }))
+        Ok(Value::String(result_msg))
     }
 }
 

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

@@ -13,25 +13,37 @@ use antigravity_sdk_rust::types::{GeminiConfig, ToolCall};
 use serde_json::Value;
 use std::sync::Arc;
 
-// Predicate to intercept dangerous shell commands containing 'rm'
 fn block_rm_predicate(tool_call: &ToolCall) -> bool {
-    tool_call.args.get("CommandLine")
+    tool_call
+        .args
+        .get("CommandLine")
         .and_then(Value::as_str)
         .is_some_and(|cmd| cmd.contains("rm"))
 }
 
-// Predicate to identify key files or production environments
 fn critical_file_predicate(tool_call: &ToolCall) -> bool {
-    tool_call.args.get("TargetFile")
+    tool_call
+        .args
+        .get("TargetFile")
+        .or_else(|| tool_call.args.get("target_file"))
+        .or_else(|| tool_call.args.get("path"))
         .and_then(Value::as_str)
-        .is_some_and(|p| p.ends_with(".key") || p.contains("production"))
+        .is_some_and(|p| {
+            std::path::Path::new(p)
+                .extension()
+                .is_some_and(|ext| ext.eq_ignore_ascii_case("key"))
+                || p.contains("production")
+        })
 }
 
-// Handler simulation for 'AskUser' decision
 fn programmatic_approval_handler(tool_call: &ToolCall) -> bool {
-    println!("[Policy Interceptor] Prompting for critical write: {}", tool_call.name);
-    // Simulating user rejection
-    false 
+    println!(
+        "\n  [ASK_USER Handler] Intercepted request for tool: {}",
+        tool_call.name
+    );
+    println!("  [ASK_USER Handler] Target arguments: {}", tool_call.args);
+    println!("  [ASK_USER Handler] Simulating user review... Decision: DENY.");
+    false
 }
 
 #[tokio::main]
@@ -42,28 +54,29 @@ async fn main() -> Result<(), anyhow::Error> {
     gemini_config.models.default.name = "gemini-3.5-flash".to_string();
     config.gemini_config = gemini_config;
 
-    // Define policy list (evaluated in reverse order)
+    // Configure policies using the recommended "Deny by Default" posture.
     let policies = vec![
         // 1. Deny everything by default
         policy::deny_all(),
-        // 2. Allow directory listings
+        // 2. Allow listing directories
         policy::allow("LIST_DIR"),
-        // 3. Deny commands containing 'rm', fallback to allow general commands
+        // 3. Allow running commands, but block dangerous 'rm' commands
         Policy::new(
             "RUN_COMMAND".to_string(),
             Decision::Deny,
             Some(Arc::new(block_rm_predicate)),
             None,
             "block-rm".to_string(),
         ),
+        // Fallback: Allow general RUN_COMMAND calls if they don't match the rm block predicate
         policy::allow("RUN_COMMAND"),
-        // 4. Prompt user before writes matching critical predicates, allow general writes
+        // 4. Allow editing/creating files, but ask the user first if it's a critical file
         Policy::new(
             "WRITE_TO_FILE".to_string(),
             Decision::AskUser,
             Some(Arc::new(critical_file_predicate)),
             Some(Arc::new(programmatic_approval_handler)),
-            "ask-critical-writes".to_string(),
+            "ask-for-critical-writes".to_string(),
         ),
         policy::allow("WRITE_TO_FILE"),
     ];
@@ -79,7 +92,7 @@ async fn main() -> Result<(), anyhow::Error> {
     agent.chat("Delete all files using rm -rf.").await?;
 
     // Blocked action - production.key write rejected by custom handler
-    agent.chat("Create a new file named production.key with secret data.").await?;
+    agent.chat("Create a new configuration file named production.key with content 'debug=true'.").await?;
 
     agent.stop().await?;
     Ok(())