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)

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)

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

Then configure Zed's settings.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)

# 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

# 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:

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