Root Channel

The root channel is the top-level channel every AHP server exposes. It carries global state — the agents the server provides, the terminals it manages, and host-level configuration — plus the catalogue events for sessions.

URI

ahp-root://

Exactly one root channel exists per server. Clients SHOULD subscribe to it during the handshake via initialSubscriptions to receive the agent list, terminal list, and host config in the same round-trip.

State

Subscribers receive a RootState snapshot:

RootState {
  agents: AgentInfo[]
  activeSessions?: number
  terminals?: TerminalInfo[]
  config?: RootConfigState
}

• agents — agent backends the server can speak to, including any protectedResources they require for authentication. See Authentication.
• activeSessions — count of non-disposed sessions. Lightweight badge counter.
• terminals — lightweight per-terminal metadata for rendering a terminal manager UI without subscribing to every terminal. See Terminal Channel for the full state.
• config — host-level configuration schema and current values.

The session list is not part of root state. Clients fetch it imperatively via listSessions and patch it from root/* notifications described below.

Methods and events on this channel

This section lists wire methods that are interpreted in the context of ahp-root://. If params.channel is some other URI, they are handled by the target channel instead.

Commands (params.channel = "ahp-root://")

Method	Kind	Why it belongs on root
initialize	request	Connection-level handshake command; scoped to the root channel.
ping	request	Connection liveness check; scoped to the root channel.
reconnect	request	Connection resume/replay negotiation; scoped to the root channel.
listSessions	request	Session catalogue lives on root (root/session* events keep the cache fresh).
resourceRead	request	Filesystem/content access is connection-level, not session-local.
resourceWrite	request	Filesystem/content access is connection-level, not session-local.
resourceList	request	Filesystem/content access is connection-level, not session-local.
resourceCopy	request	Filesystem/content access is connection-level, not session-local.
resourceDelete	request	Filesystem/content access is connection-level, not session-local.
resourceMove	request	Filesystem/content access is connection-level, not session-local.
resourceRequest	request	Permission grant/revocation flow is connection-level.
authenticate	request	Bearer-token push for protected resources is connection-level.
resolveSessionConfig	request	Pre-creation config resolution happens before any session channel exists.
sessionConfigCompletions	request	Completes dynamic fields in pre-creation session config.

Notifications (params.channel = "ahp-root://")

Method	Kind	Meaning
action	server → client notification	Root-scoped action envelope (root/* action payloads).
root/sessionAdded	server → client notification	Session catalogue entry created.
root/sessionRemoved	server → client notification	Session catalogue entry removed.
root/sessionSummaryChanged	server → client notification	Session catalogue entry mutated.
unsubscribe	client → server notification	Stop receiving root-channel messages.
dispatchAction	client → server notification	Dispatch a root-scoped client action (currently root/configChanged).

auth/required may also be emitted on ahp-root:// when the auth requirement is root-scoped; see Authentication.

Actions

Root state is mutated by action envelopes broadcast on this channel. Refer to the Root Channel Reference for the full list; the root-scoped actions are:

Action	Direction	Reducer effect
root/agentsChanged	Server	Replaces agents
root/activeSessionsChanged	Server	Replaces activeSessions
root/terminalsChanged	Server	Replaces terminals
root/configChanged	Server / Client	Merges (or replaces) config.values

All root-scoped action envelopes have channel: "ahp-root://".

Protocol Notifications

In addition to action envelopes, the server pushes per-session catalogue events to subscribers of ahp-root://. These notifications keep cached session lists in sync without subscribing to every session URI individually.

root/sessionAdded

Emitted when a new session is created.

{
  "jsonrpc": "2.0",
  "method": "root/sessionAdded",
  "params": {
    "channel": "ahp-root://",
    "summary": {
      "resource": "ahp-session:/<uuid>",
      "title": "New Session",
      "status": 1,
      "createdAt": 1710000000000,
      "modifiedAt": 1710000000000
    }
  }
}

root/sessionRemoved

Emitted when a session is disposed.

{
  "jsonrpc": "2.0",
  "method": "root/sessionRemoved",
  "params": {
    "channel": "ahp-root://",
    "session": "ahp-session:/<uuid>"
  }
}

root/sessionSummaryChanged

Emitted when any mutable field on an existing SessionSummary changes (title, status, modifiedAt, model, agent, working directory, read/done state, diff statistics, …). Only the changed fields are carried; identity fields (resource, provider, createdAt) never change and MUST be omitted.

{
  "jsonrpc": "2.0",
  "method": "root/sessionSummaryChanged",
  "params": {
    "channel": "ahp-root://",
    "session": "ahp-session:/<uuid>",
    "changes": {
      "title": "Refactor auth middleware",
      "status": 8,
      "modifiedAt": 1710000123456
    }
  }
}

Servers MAY coalesce or debounce this notification for noisy fields — for example, rapid modifiedAt bumps during a streaming turn, or frequent diffs updates during an edit burst. Clients that have no cached entry for session MAY ignore the notification.

Like all protocol notifications, the root/* events are ephemeral and are not replayed on reconnect. After reconnecting, clients SHOULD re-fetch the catalogue via listSessions.

Authentication Events

The server MAY emit auth/required on the root channel when an agent's protected resource needs (re-)authentication. See Authentication for the full flow.