Ahp Client

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

| Tool | Purpose |

| ------------------- | ------------------------------------------------------------------------ |

| connect | Open (or re-open) a WebSocket to an AHP server URL |

| send | Send a JSON-RPC message and get the response + any pending notifications |

| get_notifications | Drain the notification inbox (optionally wait N seconds first) |

| status | Check connection state, pending request count, inbox depth |

| next_id | Get a unique incrementing integer for JSON-RPC request id fields |

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

| Command | Purpose |

| ---------------- | ------------------------------------ |

| listSessions | List all session summaries |

| disposeSession | Tear down a session |

| resourceRead | Read content by URI reference |

| resourceList | List directory entries |

| resourceCopy | Copy a resource |

| resourceDelete | Delete a resource |

| resourceMove | Move/rename a resource |

| resourceWrite | Write content to a file |

| fetchTurns | Fetch historical turns for a session |

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

| Action | Effect |

| ---------------------------- | ----------------------------------------- |

| session/turnStarted | Begin a new turn with a user message |

| session/permissionResolved | Approve or deny a pending tool permission |

| session/turnCancelled | Abort an in-progress turn |

| session/modelChanged | Switch the model for future turns |

Server-originated actions

| Action | Meaning |

| --------------------------- | ---------------------------------- |

| root/agentsChanged | Available agents or models changed |

| session/ready | Session backend initialized |

| session/creationFailed | Session failed to initialize |

| session/delta | Streaming text content for a turn |

| session/toolStart | Agent is calling a tool |

| session/toolDelta | Streaming tool output |

| session/toolComplete | Tool execution finished |

| session/permissionRequest | User approval needed for a tool |

| session/turnComplete | Turn finished |

| session/error | Error during turn |

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.