version: "1.0.0" description: >- Interact with an Agent Host Protocol (AHP) server via WebSocket. Use when asked to connect to, message, or control an AHP server.

Agent Host Protocol – Copilot Skill

You have access to an MCP server (ahp-websocket) that lets you connect to an Agent Host Protocol server over WebSocket and exchange JSON-RPC 2.0 messages.

Available MCP tools

Quick-start workflow

1. connect(url: "ws://localhost:3000")
2. send initialize notification
3. wait for serverHello via get_notifications
4. subscribe to root state
5. create a session, subscribe, send turns

Protocol overview

AHP is a Redux-inspired state synchronisation protocol built on JSON-RPC 2.0 over WebSocket. The server maintains an authoritative state tree; clients apply actions optimistically and reconcile with the server's echoed actions.

Key concepts:

• Root state (ahp-root://) – lists available agents/models.
• Session state (ahp-session:/<uuid>) – per-conversation state with turns,

deltas, tool calls, and permissions.

• Actions – the sole mutation mechanism, wrapped in ActionEnvelopes with a

serverSeq.

• Subscriptions – clients subscribe to URI-identified state resources to

receive action streams.

• Notifications – ephemeral broadcasts (session added/removed) that are NOT

part of the state tree and NOT replayed on reconnect.

Connection lifecycle

1. Initialize

Send an initialize notification (no id field):

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersions": ["0.3.0"],
    "clientId": "<unique-client-id>",
    "initialSubscriptions": ["ahp-root://"]
  }
}

Then call get_notifications(wait: 2) to collect the serverHello response, which includes snapshots for any initial subscriptions.

2. Subscribe to state

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": { "channel": "ahp-root://" }
}

The response contains the current state snapshot. After subscribing, subsequent mutations arrive as action notifications.

3. Create a session

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "createSession",
  "params": {
    "session": "<provider>:/<uuid>",
    "provider": "<provider>",
    "model": "<model-id>"
  }
}

Then subscribe to the session URI. Wait for a session/ready action.

4. Send a message (start a turn)

Dispatch a session/turnStarted action as a notification (fire-and-forget):

{
  "jsonrpc": "2.0",
  "method": "dispatchAction",
  "params": {
    "channel": "<provider>:/<uuid>",
    "clientSeq": 1,
    "action": {
      "type": "session/turnStarted",
      "turnId": "<unique-turn-id>",
      "userMessage": { "text": "Hello, world!" }
    }
  }
}

Then poll get_notifications(wait: 2) to collect streaming session/delta actions until you see session/turnComplete.

5. Handle tool calls and permissions

If the agent calls a tool, the server sends:

• session/toolStart – tool invocation started
• session/permissionRequest – user approval needed

Resolve permissions with:

{
  "jsonrpc": "2.0",
  "method": "dispatchAction",
  "params": {
    "channel": "<provider>:/<uuid>",
    "clientSeq": 2,
    "action": {
      "type": "session/permissionResolved",
      "turnId": "<turn-id>",
      "requestId": "<perm-request-id>",
      "approved": true
    }
  }
}

6. Other commands

7. Reconnection

If the connection drops, call connect again and send a reconnect message instead of initialize:

{
  "jsonrpc": "2.0",
  "method": "reconnect",
  "params": {
    "clientId": "<same-client-id>",
    "lastSeenServerSeq": 42,
    "subscriptions": ["ahp-root://", "<provider>:/<uuid>"]
  }
}

Action types reference

Client-dispatchable actions

Server-originated actions

Full documentation

For complete protocol details, refer to the docs in this repository:

• Guide: docs/guide/ – conceptual overviews and walkthroughs
• getting-started.md – end-to-end example
• state-model.md – full state tree shape
• actions.md – how actions work
• reconciliation.md – write-ahead reconciliation algorithm
• Specification: docs/specification/ – normative protocol spec
• transport.md – transport requirements
• lifecycle.md – connection, session, and reconnection lifecycle
• subscriptions.md – subscription mechanics
• versioning.md – version negotiation
• Reference: docs/reference/ – complete type references
• messages.md – all state types
• actions.md – all action types with fields
• commands.md – all JSON-RPC commands
• notifications.md – all notification types
• error-codes.md – error code reference

Read these files when you need exact field names, type shapes, or edge-case behaviour.