Resource Watch Channel

Reference for ahp-resource-watch:/<id> channels — short-lived, per-connection filesystem watches that deliver batched change actions. See Resource Watch Channel specification for lifecycle and subscription semantics.

JSON Schema: state.schema.json

State Types

`ResourceWatchState`

Full state for a single resource watch, returned when a client subscribes to an ahp-resource-watch: URI.

Watches are otherwise stateless: the watcher exists to deliver {@link ResourceWatchChangedAction} events. The state carries only the descriptor of what is being watched so a re-subscribing client can recover the watch configuration after reconnecting.

Field	Type	Required	Description
`root`	URI	Yes	The URI being watched. For recursive watches this is the root of the subtree; for non-recursive watches this is the single file or directory.
`recursive`	`boolean`	Yes	`true` if the watcher reports changes for descendants of `root`; `false` if it only reports changes to `root` itself (and, when `root` is a directory, its direct children).
`excludes`	`{ items: string[] }`	No	Optional glob patterns or paths relative to `root` to exclude from change reporting.
`includes`	`{ items: string[] }`	No	Optional glob patterns or paths relative to `root` to restrict change reporting to. Omit to report every change under `root` subject to `excludes`.

`ResourceChangeType`

Discriminant for {@link ResourceChange.type}.

Member	Value
`Added`	`'added'`
`Updated`	`'updated'`
`Deleted`	`'deleted'`

`ResourceChange`

A single change observed by a resource watcher.

Field	Type	Description
`uri`	URI	The URI of the resource that changed.
`type`	ResourceChangeType	The kind of change observed.

Actions

Deliver resource changes on a watch channel. Watch state itself is immutable.

JSON Schema: actions.schema.json

`resourceWatch/changed`

A batch of resource changes observed by the watcher.

Watch events are coalesced into batches by the server to keep the action stream tractable; an empty changes.items list MUST NOT be dispatched. The reducer does not retain change history — these actions exist purely to deliver events to subscribers, who consume them directly off the action stream and apply their own logic.

Field	Type	Description
`type`	ActionType.ResourceWatchChanged
`changes`	`{ items: ResourceChange[] }`	The set of changes in this batch, wrapped for forward compatibility.

Commands

JSON Schema: commands.schema.json

`createResourceWatch`

Creates a resource watcher on the receiver's filesystem.

The receiver allocates an ahp-resource-watch:/<id> channel URI and returns it on {@link CreateResourceWatchResult.channel}. The caller then subscribes to that channel to receive resourceWatch/changed actions over the standard action envelope.

The watch lifecycle is tied to subscription: when every subscriber has unsubscribed (or the underlying connection drops), the receiver MUST release the watcher. There is no explicit dispose command — unsubscribe is the only handle the caller needs.

Like the rest of the resource* family, createResourceWatch is symmetrical and MAY be sent in either direction. Access is gated through the same permission flow as resourceRead/resourceWrite.

Property	Value
Direction	Client ↔ Server
Type	Request

Parameters:

Field	Type	Required	Description
`channel`	`'ahp-root://'`	Yes
`uri`	URI	Yes	URI to watch.
`recursive`	`boolean`	No	If `true`, the receiver MUST report changes for descendants of `uri`. If `false` (default), only changes to `uri` itself — and, when `uri` is a directory, its direct children — are reported.
`excludes`	`{ items: string[] }`	No	Glob patterns or paths relative to `uri` to exclude from reporting. Wrapped in `{ items }` for forward compatibility.
`includes`	`{ items: string[] }`	No	Glob patterns or paths relative to `uri` to restrict reporting to. Omit to report every change under `uri` subject to `excludes`. Wrapped in `{ items }` for forward compatibility.

Result:

Field	Type	Description
`channel`	URI	Receiver-assigned watch channel URI (`ahp-resource-watch:/<id>`). The caller subscribes to this URI to start receiving change events and unsubscribes to release the watcher.

Example:

jsonc

// Client → Server
{ "jsonrpc": "2.0", "id": 30, "method": "createResourceWatch",
  "params": {
    "channel": "ahp-root://",
    "uri": "file:///workspace",
    "recursive": true,
    "excludes": { "items": ["**\u002f.git/**", "**\u002fnode_modules/**"] }
  } }

// Server → Client
{ "jsonrpc": "2.0", "id": 30, "result": {
  "channel": "ahp-resource-watch:/d3a9f1e0-…"
} }

Resource Watch Channel ​

State Types ​

ResourceWatchState ​

ResourceChangeType ​

ResourceChange ​

Actions ​

resourceWatch/changed ​

Commands ​

createResourceWatch ​