# Genkit Reflection Protocol V2 (WebSocket)

This document outlines the design for the V2 Reflection API, which uses WebSockets for bidirectional communication between the Genkit CLI (Runtime Manager) and Genkit Runtimes (User Applications).

## Overview

In V2, the connection direction is reversed compared to V1:
-   **Server**: The Genkit CLI (`RuntimeManagerV2`) starts a WebSocket server.
-   **Client**: The Genkit Runtime connects to the CLI's WebSocket server.

This architecture allows the CLI to easily manage multiple runtimes (e.g., for multi-service projects) and eliminates the need for runtimes to manage their own HTTP servers and ports for reflection.

## Transport

| Feature | Specification |
| :--- | :--- |
| **Protocol** | WebSocket |
| **Data Format** | JSON |
| **Message Structure** | JSON-RPC 2.0 (modified for streaming) |

## Message Format

All messages follow the JSON-RPC 2.0 specification.

### Request
```json
{
  "jsonrpc": "2.0",
  "method": "methodName",
  "params": { ... },
  "id": 1
}
```
*Note: The `id` is generated by the sender (Manager). It can be a number (auto-incrementing) or a string (UUID). It must be unique for the pending request within the WebSocket session.*

### Response (Success)
```json
{
  "jsonrpc": "2.0",
  "result": { ... },
  "id": 1
}
```

### Response (Error)
```json
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Error message",
    "data": {
      "code": 13,
      "message": "Error message",
      "details": {
        "traceId": "...",
        "stack": "..."
      }
    }
  },
  "id": 1
}
```

The `data` field contains a `Status` object (matching V1 API) with:
-   **`code`**: Genkit canonical status code (e.g., 13 for INTERNAL, 3 for INVALID_ARGUMENT).
-   **`message`**: The error message.
-   **`details`**: Additional context, including `traceId` and `stack` trace.

### Notification
A request without an `id`.
```json
{
  "jsonrpc": "2.0",
  "method": "methodName",
  "params": { ... }
}
```

## Streaming Extension

JSON-RPC 2.0 does not natively support streaming. We extend it by using Notifications from the Runtime to the Manager associated with a specific Request ID.

| Message Type | Method | Direction | Description |
| :--- | :--- | :--- | :--- |
| **Stream Chunk** | `streamChunk` | Runtime -> Manager | Sent by the Runtime during a streaming `runAction` request. |
| **State Update** | `runActionState` | Runtime -> Manager | Sent by the Runtime to provide status updates (e.g., trace ID) before the result. |

### Stream Chunk Notification
```json
{
  "jsonrpc": "2.0",
  "method": "streamChunk",
  "params": {
    "requestId": 1,
    "chunk": { ... }
  }
}
```

### Run Action State Notification
```json
{
  "jsonrpc": "2.0",
  "method": "runActionState",
  "params": {
    "requestId": 1,
    "state": { "traceId": "..." }
  }
}
```

## Protocol Methods Summary

| Method | Direction | Type | Description |
| :--- | :--- | :--- | :--- |
| **`register`** | Runtime -> Manager | Request | Registers the runtime with the Manager and retrieves initial configuration. |
| **`listActions`** | Manager -> Runtime | Request | Retrieves the list of available actions. |
| **`listValues`** | Manager -> Runtime | Request | Retrieves the list of values (prompts, schemas, etc.). |
| **`runAction`** | Manager -> Runtime | Request | Executes an action. |
| **`cancelAction`** | Manager -> Runtime | Request | Cancels a running action. |

## Detailed API

### 1. Registration
**Direction:** Runtime -> Manager  
**Type:** Request

**Parameters:**
| Field | Type | Description |
| :--- | :--- | :--- |
| `id` | `string` | Unique Runtime ID. |
| `pid` | `number` | Process ID. |
| `name` | `string` | App name (optional). |
| `genkitVersion` | `string` | e.g., "0.9.0". |
| `reflectionApiSpecVersion` | `number` | Protocol version. |
| `envs` | `string[]` | Configured environments (optional). |

**Result:**
| Field | Type | Description |
| :--- | :--- | :--- |
| `telemetryServerUrl` | `string` | URL of the telemetry server (optional). |

### 2. List Actions
**Direction:** Manager -> Runtime  
**Type:** Request

**Parameters:** `void`

**Result:**
| Type | Description |
| :--- | :--- |
| `{ actions: Record<string, Action> }` | Object with an `actions` field containing a map of action keys to Action definitions. |

### 4. List Values
**Direction:** Manager -> Runtime  
**Type:** Request

**Parameters:**
| Field | Type | Description |
| :--- | :--- | :--- |
| `type` | `string` | The type of value to list (e.g., "model", "prompt", "schema"). |

**Result:**
| Type | Description |
| :--- | :--- |
| `{ values: Record<string, any> }` | Object with a `values` field containing a map of value keys to value definitions. |

### 5. Run Action
**Direction:** Manager -> Runtime  
**Type:** Request

**Parameters:**
| Field | Type | Description |
| :--- | :--- | :--- |
| `key` | `string` | Action key (e.g., "/flow/myFlow"). |
| `input` | `any` | Input payload. |
| `context` | `any` | Context data (optional). |
| `telemetryLabels` | `Record<string, string>` | Telemetry labels (optional). |
| `stream` | `boolean` | Whether to stream results. |
| `streamInput` | `boolean` | Whether to stream input (for bidi actions). |

**Result (Non-Streaming):**
| Field | Type | Description |
| :--- | :--- | :--- |
| `result` | `any` | The return value. |
| `telemetry` | `object` | Telemetry metadata (e.g., `{ traceId: string }`). |

**Streaming Flow:**
1. Runtime sends optional `runActionState` notifications.
2. Runtime sends `streamChunk` notifications.
3. Runtime sends final response with `result` (same structure as non-streaming).

**Bidirectional Streaming Flow (if `streamInput: true`):**
1. Manager sends `sendInputStreamChunk` notifications.
2. Manager sends `endInputStream` notification.
3. Runtime behaves as per Streaming Flow.

### 6. Cancel Action
**Direction:** Manager -> Runtime  
**Type:** Request

**Parameters:**
| Field | Type | Description |
| :--- | :--- | :--- |
| `traceId` | `string` | The trace ID of the action to cancel. |

**Result:**
| Field | Type | Description |
| :--- | :--- | :--- |
| `message` | `string` | Confirmation message. |

## Health Checks

| Check Type | Description |
| :--- | :--- |
| **Connection State** | The WebSocket connection state itself serves as a basic health check. |
| **Heartbeats** | Standard WebSocket Ping/Pong frames should be used to maintain the connection and detect timeouts. |

## Compatibility

| Version | Architecture |
| :--- | :--- |
| **V1** | HTTP Server on Runtime, Polling/Request from CLI. |
| **V2** | WebSocket Server on CLI, Persistent Connection from Runtime. |

The CLI will determine which mode to use based on configuration (e.g., `--experimental-reflection-v2`).
