Add RpcSAFE

An open-source, AI-integrated, cross-platform terminal for seamless workflows

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: add-rpc
description: Guide for adding new RPC calls to Wave Terminal. Use when implementing new RPC commands, adding server-client communication methods, or extending the RPC interface with new functionality.
---

# Adding RPC Calls Guide

## Overview

Wave Terminal uses a WebSocket-based RPC (Remote Procedure Call) system for communication between different components. The RPC system allows the frontend, backend, electron main process, remote servers, and terminal blocks to communicate with each other through well-defined commands.

This guide covers how to add a new RPC command to the system.

## Key Files

- `pkg/wshrpc/wshrpctypes.go` - RPC interface and type definitions
- `pkg/wshrpc/wshserver/wshserver.go` - Main server implementation (most common)
- `emain/emain-wsh.ts` - Electron main process implementation
- `frontend/app/store/tabrpcclient.ts` - Frontend tab implementation
- `pkg/wshrpc/wshremote/wshremote.go` - Remote server implementation
- `frontend/app/view/term/term-wsh.tsx` - Terminal block implementation

## RPC Command Structure

RPC commands in Wave Terminal follow these conventions:

- **Method names** must end with `Command`
- **First parameter** must be `context.Context`
- **Remaining parameters** are a regular Go parameter list (zero or more typed args)
- **Return values** can be either just an error, or one return value plus an error
- **Streaming commands** return a channel instead of a direct value

## Adding a New RPC Call

### Step 1: Define the Command in the Interface

Add your command to the `WshRpcInterface` in `pkg/wshrpc/wshrpctypes.go`:

```go
type WshRpcInterface interface {
    // ... existing commands ...
    
    // Add your new command
    YourNewCommand(ctx context.Context, data CommandYourNewData) (*YourNewResponse, error)
}
```

**Method Signature Rules:**

- Method name must end with `Command`
- First parameter must be `ctx context.Context`
- Remaining parameters are a regular Go parameter list (zero or more)
- Return either `error` or `(ReturnType, error)`
- For streaming, return `chan RespOrErrorUnion[T]`

### Step 2: Define Request and Response Types

If your command needs structured input or output, define types in the same file:

```go
type CommandYourNewData struct {
    FieldOne   string `json:"fieldone"`
    FieldTwo   int    `json:"fieldtwo"`
    SomeId     string `json:"someid"`
}

type YourNewResponse struct {
    ResultField string `json:"resultfield"`
    Success     bool   `json:"success"`
}
```

**Type Naming Conventions:**

- Request types: `Command[Name]Data` (e.g., `CommandGetMetaData`)
- Response types: `[Name]Response` or `Command[Name]RtnData` (e.g., `CommandResolveIdsRtnData`)
- Use `json` struct tags with lowercase field names
- Follow existing patterns in the file for consistency

### Step 3: Generate Bindings

After modifying `pkg/wshrpc/wshrpctypes.go`, run code generation to create TypeScript bindings and Go helper code:

```bash
task generate
```

This command will:
- Generate TypeScript type definitions in `frontend/types/gotypes.d.ts`
- Create RPC client bindings
- Update routing code

**Note:** If generation fails, check that your method signature follows all the rules above.

### Step 4: Implement the Command

Choose where to implement your command based on what it needs to do:

#### A. Main Server Implementation (Most Common)

Implement in `pkg/wshrpc/wshserver/wshserver.go`:

```go
func (ws *WshServer) YourNewCommand(ctx context.Context, data wshrpc.CommandYourNewData) (*wshrpc.YourNewResponse, error) {
    // Validate input
    if data.SomeId == "" {
        return nil, fmt.Errorf("someid is required")
    }
    
    // Implement your logic
    result := doSomething(data)
    
    // Return response
    return &wshrpc.YourNewResponse{
        ResultField: result,
        Success:     true,
    }, nil
}
```

**Use main server when:**
- Accessing the database
- Managing blocks, tabs, or workspaces
- Coordinating between components
- Handling file operations on the main filesystem

#### B. Electron Implementation

Implement in `emain/emain-wsh.ts`:

```typescript
async handle_yournew(rh: RpcResponseHelper, data: CommandYourNewData): Promise<YourNewResponse> {
    // Electron-specific logic
    const result = await electronAPI.doSomething(data);
    
    return {
        resultfield: result,
        success: true,
    };
}
```

**Use Electron when:**
- Accessing native OS features
- Managing application windows
- Using Electron APIs (notifications, system tray, etc.)
- Handling encryption/decryption with safeStorage

#### C. Frontend Tab Implementation

Implement in `frontend/app/store/tabrpcclient.ts`:

```typescript
async handle_yournew(rh: RpcResponseHelper, data: CommandYourNewData): Promise<YourNewResponse> {
    // Access frontend state/models
    const layoutModel = getLayoutModelForStaticTab();
    
    // Implement tab-specific logic
    const result = layoutModel.doSomething(data);
    
    return {
        resultfield: result,
        success: true,
    };
}
```

**Use tab client when:**
- Accessing React state or Jotai atoms
- Manipulating UI layout
- Capturing screenshots
- Reading frontend-only data

#### D. Remote Server Implementation

Implement in `pkg/wshrpc/wshremote/wshremote.go`:

```go
func (impl *ServerImpl) RemoteYourNewCommand(ctx context.Context, data wshrpc.CommandRemoteYourNewData) (*wshrpc.YourNewResponse, error) {
    // Remote filesystem or process operations
    result, err := performRemoteOperation(data)
    if err != nil {
        return nil, fmt.Errorf("remote operation failed: %w", err)
    }
    
    return &wshrpc.YourNewResponse{
        ResultField: result,
        Success:     true,
    }, nil
}
```

**Use remote server when:**
- Operating on remote filesystems
- Executing commands on remote hosts
- Managing remote processes
- Convention: prefix command name with `Remote` (e.g., `RemoteGetInfoCommand`)

#### E. Terminal Block Implementation

Implement in `frontend

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.