DSH plugin client resources: addresses and holders
"The resource was read and never released" is usually not a forgotten cleanup call but an address record mistaken for the resource. In DSH plugin's client resource model, an address record persists for the page lifetime while holding neither the stream nor the value. Only subscriptions and pins keep anything alive.
An address turns content into live data
Components read by address and never reference an owner's runtime.(source)
The client resource model turns one address into live data any Web Client component can read. dsh-client-resources provides ctx.resources and the global standard hook useResource; a package owning some kind of content registers a provider for its protocol, and components read that content's current state by address.
The right sidebar tabs are this model's first consumer. The goal is concrete: live data like previews and titles should not force UI components to depend on a feature plugin's runtime.
Addresses: scheme and host are readable, paths belong to the protocol
Addresses compare as strings, so different casing means different records.(source)
A resource address is a URL of the form dsh-resource://<type>/…. The host names the protocol and must be a key of ResourceProtocolMap; the path belongs to the protocol, whose owner percent-encodes it segment by segment.
Protocols needing scope put it in the path: file addresses look like dsh-resource://file/session/<sessionId>/<path>, where the path may be relative to the workspace root or absolute with a preserved leading slash, built with fileAddressFor(sessionId, cwd, path) and read back with parseFileAddress(address).
The model itself reads only scheme and host: protocolOf(address) returns the lowercase host for dsh-resource:// URLs and undefined for anything else. Addresses under other schemes — a sidebar sidebar://guide, for example — do not point at resources and read as none.
Boundaries worth remembering:
dsh-resource://file/absolute/home/me/notes.mdparses but authorizes no Session, failing withworkspace-file/unknown-workspaceinstead of borrowing the current or tab Session;DSH-RESOURCE://File/session/s1/ais a different record, andopenResourceaccepts only the canonical lowercase spellingfileAddressForproduces;- a
subagentchataddress points at an addressed subagent Conversation, whose value holds aSessionReferenceuntil the resource closes; /home/me/notes.mdis not a URL and reads asnone.
Registering providers: one per protocol
A stream must stop when its signal aborts.(source)
A protocol owner declares its value type on ResourceProtocolMap and registers one provider inside its own ctx.effect, so the protocol lives as long as the plugin. open(address, { signal }) returns a stream of RemoteResult frames — the current state first, then one per change — and must stop when signal aborts.
Failure is an ok: false frame carrying a RemoteFailure; throwing inside the stream is a programming error and is not caught. That distinction matters: business failure becomes a frame, never an exception.
Each protocol has exactly one provider, and a second registration throws. If addresses for that protocol are already held at registration time, their streams open immediately; disposing the provider ends them, and addresses read as none until it returns.
Reading: what the four states mean
failed keeps the previous value instead of blanking the interface.(source)
Every slot component receives useResource on props regardless of scope. useResource<P>(address) names the protocol as a type parameter and returns the address's current snapshot; subscribing is how you hold the resource. When another holder keeps a resource alive, a newly mounted component reads the latest value immediately without reopening the stream.
The four states:
| status | Meaning | value | failure |
|---|---|---|---|
none | No provider registered, or the address is not a resource address | undefined | undefined |
loading | Stream open, nothing produced yet | undefined | undefined |
live | Latest frame succeeded | The latest ok value | undefined |
failed | Latest frame reported failure | The retained previous ok value | That frame's RemoteFailure |
Consumers present failed themselves: the model leaves the last value beside the failure, so the body can show stale content with a notice instead of a blank panel, and the next ok frame clears it. The model produces no user-visible copy at all — which is why your component must handle failed.
Holding and releasing: subscribe or pin
When the last holder leaves, the stream aborts and the value is dropped.(source)
A resource lives while it has a holder: a subscribed useResource or a single pin.
ctx.resources.pin(address, signal) keeps a resource open until the signal aborts without subscribing; an already-aborted signal pins nothing. The right sidebar pins each open tab's address for that record's lifetime, so switching tabs and unmounting the body does not close the stream.
The first holder opens the provider's stream; the last release aborts it, drops the value, and returns the snapshot to loading (provider present) or none (absent). Frames the provider produces after that release are discarded and the iterator is returned.
ctx.resources.source(address) is the raw observable behind the hook, stable by address reference, for callers outside React; reading its snapshot alone is not holding.
"Subscribing is holding" means unmounting a component is releasing, with no extra cleanup code. Conversely, if a resource must outlive an unmount, pin it explicitly.
Value shapes and limits
Most streams push metadata only; content is read separately.(source)
The file provider's value is WorkspaceFileStat { absolutePath, version, bytes? }: the first frame comes from the host's stat, and later observations update the version. Consumers read content through the Workspace Files remote namespace themselves; Preview refreshes per tab independently.
The subagentchat provider retains the addressed Session and produces its SessionReference, releasing that reference when the resource signal aborts.
Four limits: records persist for the page lifetime — an address record stays after its last holder leaves while holding neither stream nor value, so memory grows with the number of distinct addresses read; a provider ignoring its signal runs until its next frame; the failure type is the Remote face's RemoteFailure, so providers not sourced from Remote calls must mint one; and a misspelled protocol or malformed address reads as none with no other diagnostic.
Verification: same resource, repeated reads
Cover state transitions, the single-provider rule, and post-release behavior.(source)
- Register a provider, read the address once, and assert the state moves from
loadingtolive. - Register the same protocol again and assert a throw rather than the later one overwriting.
- Unmount the component, read the same address, and assert the state returns to
loading(provider still present). - Pin the address, unmount the component, and assert the stream stays open and
live. - Abort the pin's signal and assert the snapshot returns to
loadingornone. - Read an address with a misspelled protocol and assert status
nonewith no failure.
If step 3 is still live, check whether another component or tab holds the same address — resources are shared by address, not by component.
For how the right sidebar consumes this model, see sidebar resource model; for client module injection, see client module wiring.
One line to close: addresses compare as strings, one provider per protocol, failure is a frame not an exception, failed keeps the old value, only subscription or pin holds, and records persist without holding streams.
FAQ
Yes. DSH plugin compares addresses as strings. DSH plugin accepts only the canonical lowercase spelling fileAddressFor produces, so hand-written variants are a different record.
No. DSH plugin keeps the last ok value. DSH plugin places the failure beside the value so consumers can show stale content with a notice, and the next ok frame clears it.
No. DSH plugin states a read-only snapshot is not a hold. DSH plugin keeps a resource alive only through a subscribed useResource or one pin.
No. DSH plugin reads it as none. DSH plugin offers no other diagnostic for a misspelled protocol or malformed address, only the none result.
Related Terms
- ResourceProtocolMap
- ResourceProtocolMap is the client resource protocol-to-value mapping that protocol owners extend by declaration merging.— packages/client/resources/src/index.ts
- useResource
- useResource is a global standard hook returning a resource's current snapshot by address; subscribing is holding.— packages/client/resources/src/index.ts
- pin
- pin keeps a resource open until the signal aborts without subscribing; an already-aborted signal pins nothing.— packages/client/resources/src/index.ts
- RemoteFailure
- RemoteFailure is the failure a resource failure frame carries, coming from the Remote face; non-Remote providers must mint one.— packages/client/resources/src/index.ts
Sources
- DeepSeek Harness reference - Client resources· deepseek-ai
- packages/client/resources/src/index.ts· deepseek-ai