openclaw-cascade-plugin 1.0.12 → 1.0.14

package/proto/cascade.proto

@@ -0,0 +1,297 @@
+syntax = "proto3";
+
+package cascade;
+
+import "google/protobuf/empty.proto";
+
+option csharp_namespace = "Cascade.Proto";
+
+// Session-level lifecycle for the Body host.
+service SessionService {
+  // Starts an application by name/identifier and initializes any provider state.
+  rpc StartApp(StartAppRequest) returns (Status);
+  // Resets transient state (cached trees, marks, sessions) without terminating the host.
+  rpc ResetState(google.protobuf.Empty) returns (Status);
+}
+
+// Automation entry points to query UI and execute actions.
+service AutomationService {
+  // Executes an action against a selector on the requested platform.
+  rpc PerformAction(Action) returns (Status);
+  // Returns the semantic tree snapshot for the requested platform.
+  rpc GetSemanticTree(google.protobuf.Empty) returns (SemanticTree);
+}
+
+// Vision utilities for tagged screenshots.
+service VisionService {
+  // Returns a screenshot with numeric marks mapped to UI elements.
+  rpc GetMarkedScreenshot(google.protobuf.Empty) returns (Screenshot);
+}
+
+message StartAppRequest {
+  // Friendly application identifier (e.g., process, bundle, or URL).
+  string app_name = 1;
+}
+
+message Status {
+  bool success = 1;
+  string message = 2;
+}
+
+message SemanticTree {
+  repeated UIElement elements = 1;
+}
+
+message UIElement {
+  // Stable ID within a session; provider is responsible for consistency.
+  string id = 1;
+  string name = 2;
+  ControlType control_type = 3;
+  NormalizedRectangle bounding_box = 4;
+  string parent_id = 5;
+  PlatformSource platform_source = 6;
+  // Optional accessibility/automation hints that vary by platform.
+  optional string aria_role = 7;
+  optional string automation_id = 8;
+  optional string value_text = 9;
+}
+
+message Selector {
+  PlatformSource platform_source = 1;
+  // Provider-specific path components; interpretation is platform-specific but normalized here.
+  repeated string path = 2;
+  // Optional filters to disambiguate elements.
+  optional string id = 3;
+  optional string name = 4;
+  optional ControlType control_type = 5;
+  optional int32 index = 6;
+  optional string text_hint = 7;
+}
+
+message Action {
+  ActionType action_type = 1;
+  Selector selector = 2;
+  // Optional payload for the action (text entry, numeric input, or structured JSON).
+  oneof payload {
+    string text = 3;
+    double number = 4;
+    string json_payload = 5;
+  }
+}
+
+message Screenshot {
+  bytes image = 1;
+  ImageFormat format = 2;
+  repeated Mark marks = 3;
+}
+
+message Mark {
+  string element_id = 1;
+  string label = 2;
+}
+
+message NormalizedRectangle {
+  // Normalized coordinates (0-1) relative to the capture surface.
+  double x = 1;
+  double y = 2;
+  double width = 3;
+  double height = 4;
+}
+
+enum ActionType {
+  ACTION_TYPE_UNSPECIFIED = 0;
+  CLICK = 1;
+  TYPE_TEXT = 2;
+  HOVER = 3;
+  FOCUS = 4;
+  SCROLL = 5;
+  WAIT_VISIBLE = 6;
+}
+
+enum PlatformSource {
+  PLATFORM_SOURCE_UNSPECIFIED = 0;
+  WINDOWS = 1;
+  JAVA = 2;
+  WEB = 3;
+}
+
+enum ControlType {
+  CONTROL_TYPE_UNSPECIFIED = 0;
+  BUTTON = 1;
+  INPUT = 2;
+  COMBO = 3;
+  MENU = 4;
+  TREE = 5;
+  TABLE = 6;
+  CUSTOM = 7;
+  LISTITEM = 8;  // ListItem, checkbox, radio button
+  TAB = 9;       // TabItem
+}
+
+enum ImageFormat {
+  IMAGE_FORMAT_UNSPECIFIED = 0;
+  PNG = 1;
+  JPEG = 2;
+}
+
+// Worker agent entry point for executing Skill Maps.
+service WorkerService {
+  // Starts a worker run for the given skill map and streams progress events.
+  rpc StartWorkerRun(WorkerRunRequest) returns (stream WorkerEvent);
+  // Resumes a worker run from a checkpoint and streams progress events.
+  rpc ResumeWorkerRun(WorkerResumeRequest) returns (stream WorkerEvent);
+}
+
+// Agent-to-Agent communication for coordination between agents under the same user/app.
+service AgentCommService {
+  // Registers an agent instance for a user/app context and returns an agent_id.
+  rpc RegisterAgent(AgentRegisterRequest) returns (AgentRegisterResponse);
+  // Sends a message to a specific agent_id or role.
+  rpc SendAgentMessage(AgentMessage) returns (Status);
+  // Streams inbox messages for this agent instance (at-least-once delivery).
+  rpc StreamAgentInbox(AgentInboxRequest) returns (stream AgentEnvelope);
+  // Acknowledge processing of a message to support at-least-once semantics.
+  rpc AckAgentMessage(AgentAck) returns (Status);
+}
+
+message WorkerRunRequest {
+  // High-level task description; used for planning skill selection.
+  string task = 1;
+  // Skill map identifier to execute (loaded from Firestore).
+  string skill_id = 2;
+  // Optional run identifier; generated if empty.
+  string run_id = 3;
+  // User/application/auth context for Firestore scoping.
+  string user_id = 4;
+  string app_id = 5;
+  string auth_token = 6;
+  // Optional inputs for parameterizing the run (opaque to worker).
+  map<string, string> inputs = 7;
+  // Dry-run skips side-effectful actions but still walks the plan.
+  bool dry_run = 8;
+  // Maximum number of replans during execution.
+  int32 max_replans = 9;
+}
+
+message WorkerResumeRequest {
+  // Run identifier to resume (checkpoint is loaded via context).
+  string run_id = 1;
+  string user_id = 2;
+  string app_id = 3;
+  string auth_token = 4;
+}
+
+enum WorkerEventType {
+  WORKER_EVENT_UNSPECIFIED = 0;
+  RUN_STARTED = 1;
+  STEP_STARTED = 2;
+  STEP_COMPLETED = 3;
+  STEP_FAILED = 4;
+  CHECKPOINT_SAVED = 5;
+  RUN_COMPLETED = 6;
+  RUN_FAILED = 7;
+  LOG = 8;
+}
+
+message WorkerEvent {
+  string run_id = 1;
+  string skill_id = 2;
+  WorkerEventType event_type = 3;
+  // Index of the step being processed (if applicable).
+  int32 step_index = 4;
+  // Human-readable summary of the event.
+  string message = 5;
+  // Optional error details when a step fails.
+  string error = 6;
+  // Additional metadata such as step IDs or timing.
+  map<string, string> metadata = 7;
+  // Serialized checkpoint payload (JSON string).
+  string checkpoint = 8;
+  // True when this event is emitted during planning.
+  bool planning_phase = 9;
+  // Skills selected in the current plan.
+  repeated string selected_skills = 10;
+  // Verifier reasoning or summary.
+  string verification_result = 11;
+}
+
+// A2A messages ---------------------------------------------------------------
+
+message AgentDescriptor {
+  // Unique agent instance id (assigned during registration).
+  string agent_id = 1;
+  // Role of the agent (e.g., explorer, worker, orchestrator).
+  string role = 2;
+  // Optional run identifier to scope messages.
+  string run_id = 3;
+}
+
+message AgentRegisterRequest {
+  // User/application/auth context for scoping.
+  string user_id = 1;
+  string app_id = 2;
+  string auth_token = 3;
+  // Optional role and run metadata.
+  string role = 4;
+  string run_id = 5;
+}
+
+message AgentRegisterResponse {
+  // Assigned agent id for this connection.
+  string agent_id = 1;
+}
+
+message AgentMessage {
+  // Message identifier for deduplication/idempotency.
+  string message_id = 1;
+  // User/application scope; must match registration.
+  string user_id = 2;
+  string app_id = 3;
+  // Sender metadata.
+  string sender_agent_id = 4;
+  string sender_role = 5;
+  // Target routing: either direct to agent_id or by role.
+  string target_agent_id = 6;
+  string target_role = 7;
+  // Optional run identifier to scope conversations.
+  string run_id = 8;
+  // Free-form metadata for routing/diagnostics.
+  map<string, string> headers = 9;
+  // Payload serialized as JSON string.
+  string json_payload = 10;
+  // Milliseconds since epoch when created.
+  int64 created_at_ms = 11;
+}
+
+message AgentEnvelope {
+  // The delivered message.
+  AgentMessage message = 1;
+  // Token that must be used to ack this delivery.
+  string ack_token = 2;
+}
+
+message AgentInboxRequest {
+  // Agent requesting its inbox.
+  string agent_id = 1;
+  // User/application scope; must match registration.
+  string user_id = 2;
+  string app_id = 3;
+  // Optional run filter.
+  string run_id = 4;
+  // Optional role assertion for safety.
+  string role = 5;
+}
+
+message AgentAck {
+  // Message and delivery info to mark as processed.
+  string message_id = 1;
+  string ack_token = 2;
+  // Agent acknowledging the message.
+  string agent_id = 3;
+  string user_id = 4;
+  string app_id = 5;
+}
+
+// NOTE: CodeExecutionService has been removed.
+// Cascade now executes non-UI programmatic automation (file transforms) in a sandboxed Python environment.
+

package/PHASE1_SUMMARY.md

@@ -1,191 +0,0 @@
-# Phase 1 Completion Summary
-
-## Overview
-Phase 1 of the OpenClaw Plugin for Cascade is **COMPLETE** with comprehensive test coverage.
-
-## What Was Built
-
-### 1. Project Infrastructure ✅
-- **package.json**: NPM package configuration for `openclaw-cascade-plugin`
-- **tsconfig.json**: TypeScript configuration with strict mode
-- **jest.config.js**: Jest testing framework with coverage requirements (80%+)
-- **jest.setup.js**: Test environment setup
-
-### 2. Core Components ✅
-
-#### PythonManager (`src/python-manager.ts`)
-- **Purpose**: Auto-detect and manage Python environment
-- **Features**:
-  - Auto-detect Python 3.10+ in common locations
-  - Auto-install Python on Windows/macOS/Linux
-  - Version validation and parsing
-- **Tests**: 13 passing tests
-
-#### CascadeMcpClient (`src/cascade-client.ts`)
-- **Purpose**: MCP (Model Context Protocol) client for Cascade communication
-- **Features**:
-  - Spawn Python MCP server
-  - JSON-RPC communication over stdio
-  - Tool calling and listing
-  - Request/response handling with timeouts (30s)
-  - Error handling and process management
-- **Tests**: 14 passing tests
-
-#### Config (`src/config.ts`)
-- **Purpose**: Configuration management and validation
-- **Features**:
-  - Load and validate configuration
-  - Environment variable expansion ($VAR, %VAR%)
-  - Schema validation with helpful error messages
-  - Default values management
-- **Tests**: 14 passing tests
-
-### 3. Testing Infrastructure ✅
-
-#### Test Utilities (`src/test-utils/`)
-- **mocks.ts**: Mock implementations for testing
-- **helpers.ts**: Test helper functions
-- **index.ts**: Re-exports
-
-### 4. Plugin Manifest ✅
-- **openclaw.plugin.json**: Complete plugin manifest with:
-  - Plugin metadata (id, name, description)
-  - JSON Schema for configuration validation
-  - UI hints for better UX
-  - Support for all configuration options
-
-### 5. Entry Point ✅
-- **src/index.ts**: Main plugin entry point
-  - Loads and validates configuration
-  - Initializes PythonManager
-  - Starts MCP client
-  - Registers gateway methods and CLI commands
-  - Exports types for TypeScript users
-
-## Test Coverage
-
-### Total Tests: **41 passing**
-
-| Component | Tests | Status |
-|-----------|-------|--------|
-| PythonManager | 13 | ✅ PASS |
-| CascadeMcpClient | 14 | ✅ PASS |
-| Config | 14 | ✅ PASS |
-
-### Coverage Requirements
-- Branches: 80%
-- Functions: 80%
-- Lines: 80%
-- Statements: 80%
-
-## Key Features Implemented
-
-### 1. Python Auto-Detection & Installation
-- ✅ Auto-detects Python 3.10+ in system paths
-- ✅ Supports Windows, macOS, and Linux
-- ✅ Auto-installs via appropriate package manager
-- ✅ Validates Python version meets requirements
-
-### 2. MCP Communication
-- ✅ JSON-RPC over stdio
-- ✅ Request/response handling with timeouts
-- ✅ Error handling and recovery
-- ✅ Process lifecycle management
-
-### 3. Configuration Management
-- ✅ Environment variable expansion
-- ✅ Schema validation
-- ✅ Helpful error messages
-- ✅ Default values
-
-### 4. Plugin Integration
-- ✅ OpenClaw plugin manifest
-- ✅ Gateway method registration
-- ✅ CLI command registration
-- ✅ TypeScript type exports
-
-## Configuration Options
-
-The plugin supports these configuration options (in `openclaw.plugin.json`):
-
-```json5
-{
-  cascadeGrpcEndpoint: "localhost:50051",     // Required
-  cascadePythonPath: "/usr/bin/python3",      // Optional (auto-detected)
-  firestoreProjectId: "your-project",          // Optional
-  firestoreCredentialsPath: "/path/to/creds", // Optional
-  headless: false,                             // Optional
-  actionTimeoutMs: 8000,                       // Optional
-  enableA2A: false,                           // Optional (explicit opt-in)
-  allowedAgents: ["explorer", "worker"],       // Optional
-  requireAgentConfirmation: true,             // Optional
-  verbose: false,                             // Optional
-  screenshotMode: "auto",                     // Optional
-  screenshotDir: "~/.openclaw/screenshots"    // Optional
-}
-```
-
-## What's Next (Phase 2)
-
-Phase 2 will implement the 25+ tools:
-- Desktop automation tools (9)
-- Web automation tools (14)
-- API tools (2)
-- Sandbox tools (1)
-- A2A tools for agent communication (3)
-
-## How to Test
-
-```bash
-cd openclaw-plugin
-npm install
-npm test
-```
-
-## Project Structure
-
-```
-openclaw-plugin/
-├── package.json              # NPM package
-├── tsconfig.json             # TypeScript config
-├── openclaw.plugin.json      # Plugin manifest
-├── jest.setup.js             # Test setup
-├── src/
-│   ├── index.ts              # Entry point
-│   ├── python-manager.ts     # Python management
-│   ├── python-manager.test.ts
-│   ├── cascade-client.ts     # MCP client
-│   ├── cascade-client.test.ts
-│   ├── config.ts             # Configuration
-│   ├── config.test.ts
-│   ├── types/                # Type definitions
-│   │   └── index.ts
-│   └── test-utils/           # Testing utilities
-│       ├── mocks.ts
-│       ├── helpers.ts
-│       └── index.ts
-└── README.md                 # Plugin documentation
-```
-
-## Success Criteria Met ✅
-
-- [x] All tests passing (41/41)
-- [x] Test coverage >80% (target: 80%)
-- [x] No TypeScript errors
-- [x] No linting errors
-- [x] Plugin manifest complete
-- [x] Entry point functional
-- [x] Documentation included
-
-## Time Investment
-
-- Infrastructure setup: ~30 minutes
-- PythonManager + tests: ~45 minutes
-- CascadeMcpClient + tests: ~60 minutes
-- Config + tests: ~30 minutes
-- Plugin manifest & entry point: ~20 minutes
-- **Total: ~3.5 hours**
-
-## Ready for Phase 2
-
-The foundation is solid and tested. Ready to implement the 25+ tools in Phase 2!

package/PHASE3_SUMMARY.md

@@ -1,195 +0,0 @@
-# Phase 3 Completion Summary
-
-## Overview
-Phase 3 of the OpenClaw Plugin for Cascade is **COMPLETE** with comprehensive documentation and polish.
-
-## Documentation Created
-
-### 1. Main README.md (Rewritten)
-- **Purpose**: Project overview and quick start
-- **Sections**:
-  - Feature highlights with icons
-  - Quick start guide
-  - Installation instructions
-  - Configuration options
-  - Usage examples
-  - Architecture diagram
-  - Available tools table (29 tools)
-  - Links to all documentation
-
-### 2. Integration Guide (`docs/openclaw-integration.md`)
-- **Purpose**: Complete setup and usage guide
-- **Sections**:
-  - Prerequisites
-  - Step-by-step installation
-  - Basic and advanced configuration
-  - Usage examples (Desktop, Web, A2A)
-  - Troubleshooting section
-  - Security considerations
-
-### 3. Contributing Guide (`CONTRIBUTING.md`)
-- **Purpose**: Developer onboarding
-- **Sections**:
-  - Development setup (Plugin, Python, .NET)
-  - Project structure
-  - How to add tools
-  - Testing guidelines
-  - PR process
-  - Code style guide
-  - Areas for contribution
-
-### 4. Changelog (`CHANGELOG.md`)
-- **Purpose**: Version history
-- **Content**:
-  - Version 1.0.0 with all features
-  - Breaking changes policy
-  - Upgrade instructions
-  - Future plans
-
-### 5. Troubleshooting Guide (`docs/troubleshooting.md`)
-- **Purpose**: Common issues and solutions
-- **Categories**:
-  - Installation issues
-  - Connection problems
-  - Tool execution errors
-  - A2A issues
-  - Configuration problems
-  - Performance optimization
-  - Debug mode
-
-### 6. AGENTS.md Updates
-- **Added**: Complete OpenClaw Plugin section
-- **Content**:
-  - What is OpenClaw
-  - Getting started
-  - Plugin features
-  - Development guide
-  - Testing commands
-
-### 7. Example Configuration (`docs/config-example.json5`)
-- **Purpose**: Reference configuration
-- **Includes**: All available options with comments
-
-## Documentation Quality
-
-### ✅ Completeness
-- [x] Quick start guide
-- [x] Installation instructions
-- [x] Configuration reference
-- [x] Usage examples
-- [x] Troubleshooting guide
-- [x] Developer guide
-- [x] Contributing guidelines
-- [x] Architecture overview
-- [x] Tool reference
-- [x] API documentation
-
-### ✅ Clarity
-- Clear headings and structure
-- Code examples with syntax highlighting
-- Step-by-step instructions
-- Visual diagrams (architecture)
-- Badge/shields for quick info
-
-### ✅ User-Friendly
-- Table of contents in long docs
-- Links between related docs
-- Copy-paste ready commands
-- Error messages with solutions
-- Helpful tips and warnings
-
-## Files Created/Updated
-
-```
-README.md                        [UPDATED] - Complete rewrite
-CONTRIBUTING.md                  [NEW] - Contributor guide
-CHANGELOG.md                     [NEW] - Version history
-docs/
-├── openclaw-integration.md      [NEW] - Integration guide
-├── troubleshooting.md           [NEW] - Problem solving
-├── config-example.json5         [NEW] - Example config
-AGENTS.md                        [UPDATED] - OpenClaw section
-```
-
-## Key Features Documented
-
-### For Users
-1. **29 Tools** - All tools documented with descriptions
-2. **Quick Start** - Get running in 5 minutes
-3. **Examples** - Real-world usage scenarios
-4. **Configuration** - All 13 config options explained
-5. **Troubleshooting** - Solutions to common problems
-
-### For Developers
-1. **Architecture** - How plugin connects to Cascade
-2. **Development Setup** - Step-by-step environment setup
-3. **Adding Tools** - Template and examples
-4. **Testing** - How to write and run tests
-5. **Contributing** - PR process and code style
-
-### For Maintainers
-1. **Version History** - Changelog with all features
-2. **Release Process** - How to create releases
-3. **Support Policy** - Version support commitments
-4. **Security** - Opt-in requirements for A2A
-
-## Documentation Metrics
-
-| Document | Lines | Purpose |
-|----------|-------|---------|
-| README.md | ~400 | Main project docs |
-| openclaw-integration.md | ~450 | Setup guide |
-| CONTRIBUTING.md | ~350 | Developer guide |
-| troubleshooting.md | ~400 | Problem solving |
-| CHANGELOG.md | ~200 | Version history |
-| AGENTS.md updates | ~100 | Agent rules |
-| **Total** | **~1900** | Complete docs |
-
-## Next Steps (Phase 4)
-
-Phase 4 can include:
-
-1. **CI/CD Setup**
-   - GitHub Actions workflow
-   - Automated testing
-   - NPM publishing
-
-2. **Additional Content**
-   - Video tutorials
-   - Example projects
-   - Blog posts
-
-3. **Advanced Topics**
-   - Security hardening guide
-   - Performance tuning
-   - Custom tool development
-
-## Quality Checklist
-
-- [x] All 29 tools documented
-- [x] Installation instructions tested
-- [x] Configuration examples provided
-- [x] Troubleshooting guide complete
-- [x] Contributing guidelines clear
-- [x] Code style documented
-- [x] Architecture explained
-- [x] Links between docs working
-- [x] Examples are runnable
-- [x] Error messages helpful
-
-## Success Criteria Met ✅
-
-- ✅ Comprehensive README
-- ✅ Integration guide
-- ✅ Developer documentation
-- ✅ Troubleshooting guide
-- ✅ Contributing guidelines
-- ✅ Changelog
-- ✅ Example configurations
-- ✅ Updated agent rules
-- ✅ All docs cross-linked
-- ✅ Ready for public use
-
----
-
-**Phase 3 Complete!** The OpenClaw Plugin is now fully documented and ready for the community! 🎉