Oda SDK: the runtime server

The runtime server is the serving side of the Oda SDK: it answers a program of yours over standard input and output, so you can drive DataMind Oda without the app window. This page describes the server's side of the connection, from the handshake to shutdown. Start with the Oda SDK overview if you are new to the family, and see Automation clients to connect a program of your own.

The serving connection

• One client at a time. A runtime serves one client over standard input and output; give each client its own runtime.
• One message per line. The two sides exchange newline-delimited JSON-RPC messages. The message shapes and payloads are on the SDK wire protocol page.
• Only the served methods work. A request for a method the server does not serve is refused, and the refusal names the method.

Start with one handshake

• One handshake per connection. Your client completes one initialize before it sends anything else. Until a handshake completes, prompts are refused with SDK server is not initialized.
• The handshake resolves the route. It carries the working folder and the model route: provider, model, and, optionally, a reasoning effort and a token cap. The server resolves that exact route before it accepts any prompt, and a route it cannot serve fails the handshake instead of falling back to a default.
• Refused routes. A provider the server cannot serve fails the handshake with no adapter registered for provider "<provider>"; a model that cannot run the effort you asked for fails it too.
• Checked fields. The reasoning effort must be a non-empty string (initialize reasoningEffort must be a non-empty string), and the token cap must be a positive safe integer (initialize maxTokens must be a positive safe integer). Omit a field to keep its default.
• Ready before the first prompt. The server answers the handshake only once the runtime has finished starting up, so the first prompt can use every part the runtime provides.

Sessions and prompts

• Sessions start on first use. The first prompt that names a session id creates that session's agent; later prompts with the same id reuse it.
• An accepted prompt is a receipt, not a result. It queues exactly one user message and returns its receipt right away: an object with a messageId. The id does not identify a later assistant message, a turn ending or the result of that prompt.
• Prompts queue. Prompts for one session wait their turn, and a busy session does not block prompts for other sessions.

Inline images

• Images become attachments. An inline image is stored as a durable attachment before the prompt is queued; the session keeps a reference to the stored image, not the raw bytes.
• No store, no image. When the runtime has no attachment store, it refuses the prompt rather than lose the image: SDK image prompt requires an attachment store.

Statuses and notifications

• Events stream as they happen. Every session event reaches the client as session.event while the run works.
• session.status covers the whole agent. It reports running while the agent works and idle when it stops; it is not a per-turn signal.
• Only local subagent runs are reported. subagent.finished is sent only for a subagent run that executed in the server's own process; a run that happened elsewhere is not reported through it.
• A finish carries a status. A run that completed maps to ok; a run that ended at its token limit maps to error unless the runtime is configured to treat max-token terminations as successful results.

Shutdown and teardown

• Shutdown flushes first. On a shutdown request the server writes its answer, winds the runtime down so its agents and data settle, and exits with code 0.
• New work stops. Once shutdown has begun, a prompt that needs a new session is refused with SDK server is shutting down; start a new runtime for the next run.
• Teardown failures are reported. If parts of the runtime do not dispose cleanly, the failure is reported in the shutdown answer; several failures together read SDK server teardown failed. Restart the runtime before the next run.
• A session can lose its agent. If something outside the server stops a session's agent, the server refuses that session with session agent was disposed outside the server: <id>; the session cannot continue.

Questions, answered

What happens if a prompt arrives before the handshake?

The server refuses it with SDK server is not initialized. Complete one successful initialize first; if the handshake itself failed, its error says why.

Does every prompt need its own handshake?

No. One handshake covers the connection: the route is resolved once, and sessions start on first use of their session id.

Why did the handshake fail with no adapter registered for provider "<provider>"?

The provider you named cannot be served by this runtime, so the route could not be resolved. Name a provider and a model this runtime can serve, then handshake again; the route does not fall back to a default.

What comes back when a prompt is accepted?

Its receipt, an object with a messageId, straight away. It confirms that exactly one user message was queued; it does not identify a later assistant message, a turn ending or the result of that prompt.

What happens to an image I send with a prompt?

It is stored as a durable attachment before the prompt is queued, and the session keeps a reference to the stored image. Without an attachment store the server refuses the prompt rather than lose the image: SDK image prompt requires an attachment store.

What do running and idle describe?

The whole agent, not one turn: running while the agent works, idle when it stops.

Which subagent runs does subagent.finished report?

Only runs that executed in the server's own process. A subagent run that happened elsewhere is not reported through it.

A run stopped at its token limit. Why does the server report error?

By default a max-token stop is not a success: a completed run maps to ok, and a run that ended at its token limit maps to error unless the runtime is configured to treat max-token terminations as successful results.

What happens to a prompt while the server is shutting down?

A prompt that needs a new session is refused with SDK server is shutting down. The runtime is finishing its shutdown; start a new runtime for the next run.

The shutdown answer reports a teardown failure. What should I do?

Several parts of the runtime did not dispose cleanly at once; several failures together read SDK server teardown failed, while a single failure is reported as itself. Restart the runtime before the next run.

Why was my session refused with session agent was disposed outside the server?

Something outside the server stopped that session's agent, so the server will not drive the session further. Continue in a new session.

Why must standard output carry only protocol messages?

That channel carries the protocol for the client, so a deployment must keep every other writer, a logger included, off it; this requirement is checked when the runtime is deployed.