DeepSeek Harness API Gateway and remote method calls

The DeepSeek Harness API Gateway is a typed bridge between Host business services and Client code. It uses Typert descriptors to expose only explicitly marked methods, generate concrete Client functions and types, and carry calls over the existing /api connection. The design avoids treating every Host method as remotely callable and keeps the process boundary visible in code.

This is an independent explanation of the official Chinese API Gateway document. Use the upstream guide and source tree when implementing a remote method.

What the API Gateway solves

Host code can access files, sessions, tools, and other privileged resources that should not be imported directly into a browser Client. The gateway publishes a selected business API while preserving typed arguments and results.

This gives DeepSeek Harness three useful properties:

• an explicit allowlist of remote methods;
• generated Client contracts instead of handwritten request wrappers; and
• a single runtime transport that can validate descriptors at the boundary.

The gateway is not a shortcut for sharing arbitrary Host objects. A value that is safe and meaningful inside one process may be impossible or unsafe to serialize across the connection.

Root services and scoped services

Typert distinguishes two kinds of remote API surface:

• @Remote marks a root Host service; and
• @RemoteScope marks behavior tied to a scoped Cordis context.

Only decorated methods are exposed. An unmarked helper remains private to the Host even if it is public in TypeScript. That explicitness is a security feature: refactoring a class should not accidentally publish every new method to the Client.

Scoped APIs are useful when a call belongs to a particular Agent or context rather than to the process as a whole. On the Client, generated calls appear under namespaces such as ctx.remote.<namespace> or agentCtx.remote.<namespace>.

Service implementation and object identity

Remote services typically extend TypertRemoteService or use bindTypertRemote. The mechanism connects a service definition to the generated gateway descriptors and runtime handler.

Complex Host objects require special care. Instead of serializing a live object graph, expose a stable identifier and resolve it through a Host-side lookup map. This preserves ownership and prevents methods from depending on prototypes, open handles, or other process-local state that cannot cross the wire.

Prefer plain, validated data-transfer values for arguments and responses. If a result needs behavior, return data and let the Client provide its own presentation logic.

Generated Client functions, not a dynamic Proxy

The Client API is generated as concrete functions. It is not a JavaScript Proxy that invents methods at runtime. Concrete generation improves discoverability, static type checking, tree analysis, and failure visibility during the build.

The generation pipeline is intentionally strict. When a Host descriptor changes, generated Client contributions must be refreshed before dependent layers compile. This is why the root build follows Host, then Client, then Web order. See the development setup guide for the complete contributor workflow.

Runtime request format

At runtime, gateway calls reuse the connection and /api route. A call is conceptually sent to:

POST /api/<namespace>/<method>

with a payload shaped like:

{ "args": [] }

The descriptor determines how arguments and results are encoded and validated. Namespace and method names therefore form part of the remote contract; changing them can break Client callers even when the underlying Host logic still works.

Cooperative cancellation

A remote function can support cooperative cancellation when its final parameter is signal: AbortSignal. The position and type are part of the convention. The Host implementation must pass the signal into cancellable work and check it during long operations.

Cancellation is cooperative, not forced process termination. If an implementation ignores the signal while it waits on an external operation, the Client can request cancellation but the work may continue until that operation returns.

Security and trust boundaries

Treat every Client request as untrusted input, even when the UI is shipped with the same project. Validate descriptors, arguments, object identifiers, and authorization context on the Host. Do not rely on TypeScript types at runtime; they disappear after compilation.

Before exposing a method, ask:

• does the Client need this capability, or only a smaller operation?
• can each argument be serialized and validated?
• could an identifier access an object outside the current Agent scope?
• should the operation be cancellable?
• can the response reveal filesystem paths, credentials, or private session data?

The broader plugin and scope model is covered in DeepSeek Harness architecture and the glossary.

Debugging gateway failures

If a Client call is missing, confirm that the Host method is explicitly marked and generation ran before the Client build. If the call exists but returns an error, check the namespace, method name, encoded arguments, Host lookup, and runtime descriptor validation. If cancellation fails, verify both the final AbortSignal parameter and the downstream operation that must observe it.

Separating generation failures from runtime transport failures prevents unnecessary UI debugging when the contract was never emitted.

Official source

This tutorial was independently created from the official DeepSeek Harness API Gateway guide, reviewed on 2026-08-20. The upstream document remains authoritative for decorators, generated contributions, and transport behavior.