Remote calls, streams and events

DataMind Oda's screens and its extension packages call the host that serves them through one layer: short calls that carry a request and an answer, long-lived streams that carry items in both directions, and events the host forwards to the interface. This page is the reference for that layer, from writing a Remote method in a package to the messages on the wire, so you can author a method, read a trace, debug a connection or build a client of your own. The message-level view is also on The Oda Remote API, and what a build generates for a Remote-capable package is on Plugin artifacts and the catalog. Oda also defines and runs packages in a chat itself, covered by The host half of a dynamic package and The browser half of a dynamic package.

Mark a method as Remote

An extension package exposes a method to the other side of the boundary by marking it as Remote and binding its owner to a service; the runtime then carries calls, streams and cancellation between the two sides. Markers are written in TypeScript on the method itself:

• Public instance methods only. A marker needs a public, non-static instance method with a string name and a concrete implementation; private or static methods, methods without an implementation and generic methods are refused with Remote decorators require a public instance method with a string name.
• One marker per method. Two markers that disagree on one method fail with Remote method "<method>" has conflicting invocation markers; keep the single marker that says how the method is called.
• The stream option is exact. A stream marker's options object must be exactly { mode: 'stream' }; anything else fails with Remote options must contain exactly mode: "stream". Use the plain or named marker for a method that does not stream.
• Parameters are plain named bindings. Rest parameters, default values and destructured bindings are refused, so a call carries exactly the arguments the method declares. A parameter written as T | undefined still counts as required; only an optional parameter may be left out of a call.

Bind the methods to a service

A marked method becomes callable once its owner is bound:

• A service base class. A class that extends the runtime's service base class binds its marked methods when it is constructed.
• A bind helper. An instance that does not extend the base class can be bound with a bind helper that takes the service key and, optionally, a namespace.
• One descriptor on the class. The markers record one descriptor on the class: frozen, non-enumerable and carrying a version, currently 1. Markers read back in declaration order, and a descriptor under another version is refused.
• The binding is validated and frozen. Binding checks the service key and the namespace first, and the record it produces (the service, its key and its namespace) is frozen. A second binding of the same service is refused.

What a call carries

• The invocation context. Inside a Remote method, ctx.invocation describes the call in progress: the request it belongs to (its namespace, its method and the arguments as received), the service it reached, the peer that made it and the signal. Outside a Remote call the same property reads as undefined, so code shared with other paths can check it first.
• Cancellation is injected. Declare signal: AbortSignal as the method's final parameter to cooperate with cancellation; the runtime provides the signal, and it never travels as a call argument. A signal declared anywhere else fails with Remote cancellation signal must be the final parameter. React to it to stop your work when the caller goes away.

Write a streaming method

• Declaration. A streaming method is declared with @Remote({ mode: 'stream' }) and returns an Iterable<Out>, an AsyncIterable<Out> or a RemoteStream<Out, In>. Another return shape, a promise included, is refused with stream Remote methods must return Iterable<Out>, AsyncIterable<Out>, or RemoteStream<Out, In>. Each yielded item travels on the logical stream as the method produces it, so a caller sees items while the method still runs.
• The caller's handle. On the calling side, a streaming call is a handle with send(item), end() and dispose(): send adds one item to the caller's side of the stream, end half-closes it so no further items follow, and dispose cancels the stream and ends the caller's iteration.
• When send throws. It throws when the item is not a lossless JSON value, when the uplink has already been ended, or when the stream has terminated; nothing is delivered.
• Items wait for the open. An item the caller sends before the stream has opened is queued and sent once the stream opens.
• The uplink is read once. The method reads the caller's items through ctx.invocation.uplink(). It is available once per call, and asking for it a second time throws.
• Leaving early cancels. When the caller breaks out of the item loop early, the stream is cancelled, and items that were never read are dropped rather than delivered later.
• One handle, one connection. A handle stands for one connection generation: when the connection is lost, iteration fails with the connection error and the handle is finished; start the call again for a new stream.

Values that cross

The same lossless checks cover clients, gateways and mocks, so a value that cannot round-trip unchanged is refused wherever it would cross: call arguments, results, uplink items and forwarded-event payloads.

• What crosses. null, strings, booleans, finite numbers, plain objects with enumerable fields and dense arrays.
• What is refused. undefined fields, big integers, NaN, infinities, -0, cycles, class instances and other non-plain objects, functions, accessor or non-enumerable fields, symbol keys and sparse arrays.
• An item may omit its value. At the top level, an uplink item sent as undefined crosses as an item with no value; nested values are still checked.
• Bytes only in a unary result. Binary data (Uint8Array) may cross only as the single result of a unary call, directly or nested inside it; parameters, events and stream items stay JSON only, and another use is refused with Remote Uint8Array is only supported in unary results.
• Owned values are released once. A value can cross as invocation-owned: the invocation releases it at most once, the release never throws, and repeating it is harmless.

How calls are named

• Endpoint. A call is addressed by its endpoint, <namespace>/<method>; a registered invocation carries the full id <package>#<namespace>/<method>.
• Schema and package keys. A generated schema is addressed as <package>#<name>, and one package's contribution per side as <package>#<side>, where the side is host or client. The # marks where the package part ends.
• The segment grammar. Every segment of a call name (a namespace, a method, an export name, a service key or a scope key) may contain only letters, digits, _, $, . and -. A lone . or .. is refused, and a # is refused inside a name; a name outside the set is refused with a message that ends must contain only RPC endpoint segment characters.

Calls

• A call is addressed. It names an endpoint, a namespace and a method, and carries its arguments as one plain object.
• Arguments are checked before the method runs. A call whose shape does not match the endpoint fails instead of reaching the method.
• One request, one answer. A call travels as one request message and is answered by one response message.
• Answers are result envelopes. An answer reports success as { ok: true, value }, or failure as { ok: false, error }.
• An aborted call settles as cancelled. It reports gateway/cancelled with the message Remote invocation "<endpoint>" was aborted, not a failure from the method.

Streams

Streams are logical: they share the one WebSocket connection the client keeps open, each under its own stream id.

On a stream, each side sends a small set of frames:

• Items wait for the reader. An item that arrives before the method reads its uplink waits in the stream's inbox instead of being lost.
• Late items fail only their stream. An uplink item sent after end fails that stream with gateway/protocol; the connection stays open for its other streams.
• Stray frames are dropped. A frame that names a stream the connection does not know, or has already finished, is ignored. The one violation that closes the whole connection is a second open for a stream id that is already open.
• One consumer per stream. A logical stream serves exactly one consumer, and opening a second one fails. When several parts of the interface need the same data, the client shares one stream between them instead of opening another.
• A mismatch fails early. A method that is a stream must be opened as a stream, and a plain call must not be opened as one; the mismatch fails before the method runs.
• Reconnects start fresh. When the connection drops, the client reconnects and each stream reopens on the new connection. While a replacement is being established, the interface keeps showing the state it already had; nothing from the old connection is replayed, so a consumer re-reads the state it needs. Connection states and recovery covers the reconnection itself.
• Only admitted callers connect. Before any stream opens, the connection must come from a caller the host trusts and can authenticate: a caller it does not trust gets 403, and one it cannot authenticate gets 401.

The session surface

• One namespace carries most of the interface. The session namespace lists and searches sessions, creates and renames them, forks them and works with branches, selects models, sends prompts, updates the queue, cancels work, and pages history.
• Streams keep a chat current. The session's follow and control streams are how a chat stays current in the interface; both obey the reconnect rules above.
• Session changes also arrive as events. A session added or removed, its status, its activity, its branches and its errors are forwarded to the interface, as the next section describes.

Forwarded events

• A fixed list. The interface subscribes to events from a list fixed at build time, twenty-five entries in the current set; a name outside the list is never forwarded.
• What the list carries. Session changes (a session added or removed, its status, its activity, its branches and its errors), preset selection, goal activation changes, model adapter updates, permission catalogue changes, scheduled-task changes, settings updates, and the interface's own components (commands, credentials and plugins).
• Two entries answer back. An approval request and a user question arrive as requests: the first client to answer settles the request, the other clients are told it was cancelled, and a client that does not answer can hand the request to the next handler. When every client hands it on, the host's own fallback answers.
• The stream opens with a readiness frame. Its first item confirms readiness and carries the host's home folder, which the interface uses to shorten displayed paths.
• Only requests are replayed. A one-way event missed while disconnected is gone; a request still waiting for an answer is sent again to the replacement connection.

Account states

• The state and its changes. The interface can read the account state, and subscribe to it: it receives an initial complete state, then each change.
• Profile and balance. Both can be read; each reads as null when the grant to the account is absent or has changed.
• Starting a sign-in. A sign-in can be started from the web interface or from the desktop app.
• Cancelling names the attempt. A cancellation names the specific attempt, so a stale screen cannot cancel a newer sign-in.
• Disconnecting stops the watching, not the sign-in. An interface that disconnects stops observing the account; it finds the current state again by subscribing, but it cannot resume a sign-in attempt after the host has exited.
• Signing out is local and backgrounded. Signing out removes the local grant and revokes it in the background; the saved API keys are not deleted.
• Credentials stay out of reach. Account credentials never enter model prompts, session logs or tool results.

Limits

• Lossless JSON only. Every value that crosses the layer must round-trip unchanged; Values that cross lists what crosses and what is refused.
• A bounded uplink. A stream's uplink buffers at most 262,144 bytes (256 KiB) of frames by default. A client that overruns this fails its own stream with gateway/uplink-overflow, and later items are dropped; uplink items are never replayed.
• A refused item fails its stream. An uplink item that fails the value checks fails the whole stream with gateway/input-invalid, and the failure names the uplink field.
• The heartbeat is also the deadline. The connection is pinged every two seconds by default, and that interval is both the ping cadence and the answer deadline: a peer that misses two intervals in a row has its connection terminated. The interval is a deployment setting, so it can be raised where the default is too quick for the machines involved.
• Text messages only. The connection carries text messages; a binary message closes it.

Close codes

A connection ends with a close code and, usually, a reason:

When a call or stream fails

• One failure class. Failures come as one RemoteError carrying a stable code of the form <domain>/<reason>, the endpoint it belongs to and, when one field is at fault, that field's name.
• Three universal codes. gateway/bad-request when the request does not satisfy the endpoint, and that failure can carry an issues list describing what was wrong; gateway/cancelled when the call was cancelled; and gateway/internal for a failure the layer could not classify.
• By code, never by class. A failure is recognised structurally, not by its class, so one that arrived across a bundle boundary still reads correctly. Branch on the code, never on an instance check.
• The layer's own vocabulary. The codes that mark the layer's problems include gateway/cancelled for an aborted call, gateway/uplink-overflow for an overrun uplink, gateway/protocol for an uplink item after the stream had ended, and gateway/input-invalid for a value or field that failed validation. A failure the layer cannot classify reports gateway/internal with empty details.
• The rest of the vocabulary covers dispatch problems. An endpoint that cannot be found or is ambiguous, a service that is not available, and arguments or results that fail validation.
• Method failures pass through. A failure from the method itself passes through unchanged; the layer marks only its own problems.
• Broken streams fail rather than guess. A stream whose sequence breaks fails instead of being applied: for example, session assistant stream skipped revision <n> and session event stream emitted an entry before its opening cursor.

Questions, answered

What happens to open streams when the connection drops?

Nothing is replayed. When the client reconnects, each stream reopens on the new connection and re-reads the state it needs; items and notifications from the old connection are never sent again. While the replacement is being established, the interface keeps showing the state it already had. Connection states and recovery covers the recovery itself.

Why did the connection close with code 1008?

The reason invalid Remote stream request covers a malformed message, an unknown message type, or a second open for a stream id that is already open. Check the frames against the shapes on this page; a duplicate open is the one violation that closes the whole connection.

Why was my uplink item not lossless JSON?

The value used something the JSON subset does not admit, such as an undefined field, a big integer, NaN, an infinity, negative zero, a cycle, a class instance, or an accessor, hidden or symbol field. Send plain objects, dense arrays and ordinary JSON values instead. The stream the item was sent on fails with gateway/input-invalid.

Can two consumers watch the same stream?

No. A logical stream serves exactly one consumer, and opening a second one fails. When several parts of the interface need the same data, the client shares one stream between them instead of opening another.

How long may the connection stay silent?

It is pinged every two seconds by default, and that interval is also the deadline for the answer. A peer that misses two intervals in a row loses the connection. The interval is a deployment setting, so it can be raised where the default is too quick for the machines involved.

How much can a stream's uplink hold?

262,144 bytes (256 KiB) of frames by default. Over that, the stream fails with gateway/uplink-overflow and later items are dropped. Uplink items are never replayed, so anything that did not get through is lost.

Are forwarded events replayed after a reconnect?

One-way events are not: a notification missed while disconnected is gone. A request that is still waiting for an answer is different; it is sent again to the replacement connection so it can still be answered.

Can a private or static method be marked as Remote?

No. A marker needs a public, non-static instance method with a string name and a concrete implementation; private or static methods, methods without an implementation and generic methods are refused with Remote decorators require a public instance method with a string name. Mark a public instance method instead.

Why must the signal parameter be last?

Because the signal is injected, not sent: the runtime provides it at call time, and a declaration that does not end with it is refused with Remote cancellation signal must be the final parameter. Declare signal: AbortSignal as the method's last parameter and react to it when the caller goes away.

Why did my send() call throw?

send throws when the item is not a lossless JSON value, when the uplink has already been ended, or when the stream has terminated. Nothing is delivered when it throws, so fix the value or stop sending to an ended or finished stream.

Why should I check the failure code instead of using instanceof?

Because an instance check does not survive a bundle boundary: a failure is recognised structurally, not by its class. Read the stable <domain>/<reason> code and branch on that.

How is this different from the Oda SDK?

They are different surfaces. This layer connects DataMind Oda's own screens and extensions to the host that serves them. The SDK is for a program of your own: a client process talks to a runtime over standard input and output, with the messages in The Oda SDK wire protocol. Start from the Oda SDK overview, or read Automation with Oda for the serving profiles.