DSH plugin API gateway: @Remote in DeepSeek Harness

DeepSeek Harness's Typert API gateway exposes host-side services safely to the client: @Remote and @RemoteScope choose which methods open up, and TypertLookupMap declares the association between host objects and wire identity (source). Every action in the UI is really a "browser → host" call, and what can be called and on which object are decided by this controlled channel. This piece covers how that exposure mechanism works and how a plugin joins it; how front-end modules load is in client modules explained, and the layer map in DeepSeek Harness architecture.

Why an API gateway is needed

Host and client live in two worlds: the back end runs in Node and the UI in the browser, so the two can neither reference each other's objects directly nor should they flatten every capability — the API gateway is the controlled channel designed for that cross-boundary call (source). Break the problem apart:

1. Two worlds cannot call each other directly: the browser cannot hold a Node object reference, and Node cannot render the page; the call must go through some serialisation and routing, which is what the gateway does.
2. Capabilities must not be flattened: back-end services inevitably contain methods meant for internal use only, and exposing them all would turn the internal structure into a public interface.
3. Cross-process objects need identity: when what is exposed is not just a method but the capabilities on an object, the gateway must know "which instance this request should land on", or it cannot route.
4. The protocol should not be rewritten per plugin: unified on Typert, a plugin only annotates and implements by convention and gets consistent exposure and routing, rather than building its own communication layer.

What the DeepSeek Harness API gateway does

The DeepSeek Harness API gateway exposes host-side services safely to the client, letting the front end call controlled back-end methods (source). Three points:

1. Controlled exposure: not every method is callable from the front end — the callable set is decided by annotation, and the default is narrow, so opening up is an explicit act.
2. Built on Typert: the gateway runs on the Typert mechanism, so plugins do not build their own protocol and the ecosystem avoids protocol fragmentation.
3. It serves the Web GUI link: it sits opposite client modules, one front and one back, together supporting UI calls to back-end capabilities; without it the page would be a static shell.

Choosing which methods and objects to expose

In DeepSeek Harness, @Remote and @RemoteScope choose which methods open to the client, while TypertLookupMap declares the association between host objects and wire identity (source). Taken apart:

1. @Remote decides "which methods": only annotated methods open through the gateway; the unannotated part stays internally visible, which forms the security floor.
2. @RemoteScope decides the scope: it delimits the boundary under which a set of related capabilities applies, so a group opens together rather than being granted piece by piece.
3. TypertLookupMap decides "which instance to route to": it maps host objects to their network identity, and the request finds the right target from it — an indispensable step when exposing objects across processes.

Why wire identity matters

In cross-process exposure an "object" cannot travel by reference as it does inside one process; it needs an addressable network identity (wire identity), and what TypertLookupMap declares is exactly the correspondence between host objects and that identity (source). Three points:

1. Without identity there is no routing: a request carries only an identifier over the wire, and the gateway must reconstruct "which object this is" from it; a missing mapping means failed routing.
2. The mapping is registered explicitly: the association between identity and object is declared in the lookup table, not guessed, so it is auditable rather than an implicit convention.
3. It is the premise of exposing object capabilities: only after the identity is established can a call land on the right instance, so exposing object-level capability has meaning.

How a plugin joins the gateway

A DSH plugin joins the gateway through entries such as ctx.typert.lookups and implements the services it wants to expose under the TypertRemoteService convention (source). Two points:

1. Register into the lookup table: ctx.typert.lookups is where a plugin registers its services, and only then can the gateway resolve them; this step is distinct from declaring a front-end entry in the package, and both halves are needed for a complete link.
2. Implement by the remote-service convention: implementing TypertRemoteService lets a plugin's capabilities be called by the client as controlled methods — the convention is unified, so plugins do not negotiate their own communication. For a plugin that links front and back, look under Settings → Plugin Market, which is DSH Plugin Hub.

How the gateway and front-end modules cooperate

The API gateway and client modules are the two hands of the DeepSeek Harness Web GUI link: the former decides which back-end capabilities the UI can call and which object a call lands on, while the latter decides which front-end modules the page loads (source). Trace it as a sequence:

1. Front-end modules come first: a plugin's UI code enters the entry graph via the dsh.client declaration and is loaded onto the page.
2. Then the gateway connects the back end: an action in the UI crosses to the host through @Remote-annotated methods, routed by the lookup table to the right service instance.
3. Both halves are needed: declaring only a front end with no gateway leaves the UI with no data source; exposing only the back end with no front-end module leaves the capability with no trigger.
4. Diagnose in stages: if the UI element does not appear, check front-end modules; if it appears but does nothing when clicked, check the gateway side.

Notes on the API gateway

Read the gateway as a "controlled channel between host and client" and it will not blur with front-end loading.

1. Exposure needs explicit annotation: unannotated methods do not open, which is the security floor.
2. Objects need the lookup map to route: cross-process exposure needs identity mapping, or the target instance cannot be found.
3. Scopes open a group together: @RemoteScope delimits the boundary of a set of capabilities rather than granting piece by piece.
4. It divides work with front-end modules: modules handle loading, the gateway handles calls, and both are needed.
5. Plugins implement by convention: go through ctx.typert and TypertRemoteService, not a self-built protocol.
6. It is one link of the Web GUI: a UI-less run may not involve it; when the UI fails, judge which side it falls on.
7. Its coordinates in the tree in DeepSeek Harness architecture; front-end loading in client modules explained.

Source: DeepSeek Harness docs - API gateway, docs - client modules subsystem.