ChatGPTClaudeGrok / X / CursorGemini

DSH plugin client resources: addresses and holders

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessClient resourcesuseResourceHolding and release
DSH plugin client resources: address construction rules, one provider per protocol, four read states, and holding through subscription or pin.

"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.md parses but authorizes no Session, failing with workspace-file/unknown-workspace instead of borrowing the current or tab Session;
  • DSH-RESOURCE://File/session/s1/a is a different record, and openResource accepts only the canonical lowercase spelling fileAddressFor produces;
  • a subagentchat address points at an addressed subagent Conversation, whose value holds a SessionReference until the resource closes;
  • /home/me/notes.md is not a URL and reads as none.

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:

statusMeaningvaluefailure
noneNo provider registered, or the address is not a resource addressundefinedundefined
loadingStream open, nothing produced yetundefinedundefined
liveLatest frame succeededThe latest ok valueundefined
failedLatest frame reported failureThe retained previous ok valueThat 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)

  1. Register a provider, read the address once, and assert the state moves from loading to live.
  2. Register the same protocol again and assert a throw rather than the later one overwriting.
  3. Unmount the component, read the same address, and assert the state returns to loading (provider still present).
  4. Pin the address, unmount the component, and assert the stream stays open and live.
  5. Abort the pin's signal and assert the snapshot returns to loading or none.
  6. Read an address with a misspelled protocol and assert status none with 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.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Are DSH plugin resource addresses case-sensitive?

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.

Does a DSH plugin failed state drop the previous value?

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.

Does reading a DSH plugin source snapshot count as holding?

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.

Does a misspelled DSH plugin protocol raise an error?

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