dirigate/HELP_DEMO.md

# ACP Mocker - Help Feature Demo

## Overview

The ACP mocker now responds to the word "help" sent as a regular message in any session, returning comprehensive diagnostic information about the mocker's configuration.

## Key Points

### Transport Architecture

**stdio is PRIMARY**: The ACP protocol uses stdio (stdin/stdout) as the primary transport method. This is how editors like Zed communicate with agents - they launch the agent as a subprocess and use JSON-RPC over stdio.

**HTTP is ADDITIONAL**: HTTP transport with SSE (Server-Sent Events) is an additional capability we implemented for testing purposes. It's not the standard way editors interact with ACP agents.

### Content Delivery

All response content is sent via `session/update` notifications:
- **stdio mode** (primary): Notifications are automatically written to stdout
- **HTTP mode** (testing): Client must subscribe to SSE at `/events/{session_id}`

The `session/prompt` response only contains `{"stopReason": "end_turn"}` - the actual content comes through notifications.

## How to Use

### 1. Start the Mocker (HTTP mode for testing)

```bash
cargo run --package dirigent_acp_mocker -- serve \
  --fixtures packages/dirigent_acp_mocker/examples/basic.yaml \
  --port 8080
```

### 2. Start with stdio (Primary mode, for Zed)

```bash
cargo run --package dirigent_acp_mocker -- serve \
  --fixtures packages/dirigent_acp_mocker/examples/basic.yaml \
  --stdio
```

Then configure Zed's `settings.json`:
```json
{
  "agent_servers": {
    "dirigent-acp-mocker": {
      "command": "G:/dev/projects/dirigent/target/debug/dirigent-acp-mocker.exe",
      "args": [
        "serve",
        "--fixtures",
        "G:/dev/projects/dirigent/packages/dirigent_acp_mocker/examples/basic.yaml",
        "--stdio"
      ]
    }
  }
}
```

### 3. Test via HTTP (Testing Only)

```bash
# Initialize
curl -X POST http://localhost:8080/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": 1,
      "clientCapabilities": {}
    },
    "id": 1
  }'

# Create session
curl -X POST http://localhost:8080/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "session/new",
    "params": {},
    "id": 2
  }'

# Send "help" message (replace SESSION_ID with actual ID)
curl -X POST http://localhost:8080/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "session/prompt",
    "params": {
      "sessionId": "SESSION_ID",
      "prompt": [
        {
          "type": "text",
          "text": "help"
        }
      ]
    },
    "id": 3
  }'

# To see the actual response content, subscribe to SSE (in separate terminal):
curl -N http://localhost:8080/events/SESSION_ID
```

### 4. Test via Python Script

```bash
# Using the test helper
python tools/test_help.py --port 8080
```

## What You Get

When you send "help" as a message, you'll receive a diagnostic response including:

- **Mocker Information**: Name, version, transport clarification
- **Fixture Configuration**: Version, available sessions, session IDs
- **Streaming Settings**: Enabled/disabled, chunk size, interval, jitter
- **Responder Configuration**: Default strategy, keyword mappings, random corpus
- **Active Sessions**: Currently active session count and IDs
- **Transport Explanation**: Clear explanation that stdio is primary, HTTP is for testing
- **Available Methods**: All ACP methods and extensions
- **Keywords to Try**: List of configured keywords that trigger specific responses

## Alternative: Method-Based Help

You can also call `_dirigent/help` as a JSON-RPC method:

```bash
curl -X POST http://localhost:8080/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "_dirigent/help",
    "id": 1
  }'
```

This returns the same diagnostic information but as structured JSON rather than formatted markdown.

## Why This Matters

1. **Debugging**: Quickly check if fixtures loaded correctly
2. **Configuration Verification**: See what keywords and responders are active
3. **Testing**: Understand streaming settings and session state
4. **Learning**: Get inline documentation about available methods
5. **Transport Clarity**: Understand that stdio is primary, HTTP is for testing only