The Oda SDK client

The Oda SDK client is the TypeScript package that starts an Oda runtime for you and drives its turns from your own program. Use it when a script or an internal tool of yours should call DataMind Oda on its own.

The family and its reading order start at Oda SDK overview; the raw messages the client and the runtime exchange are in The Oda SDK wire protocol, and the serving side is in Running an Oda runtime server.

Launch options

The client starts the runtime for you, over standard input and output, the first time you need it. You never start the runtime by hand.
Give the client an absolute working folder. It resolves the folder before the start-up handshake, so a relative path cannot be resolved twice.
Binary. By default the client finds the runtime executable itself. Point it at a specific executable when your setup keeps the runtime elsewhere.
Profile. The runtime starts on a profile, and the client's default profile is sdk. The profiles Oda ships are listed on Oda profiles and launchers.
Patches. You can add configuration patch files for the runtime. The client applies its own patch first, and yours after it, in the order you list them.
Version check. The client requires a runtime of the same version as itself, and checks this when it launches. At the start-up handshake it also checks that the answer carries the runtime's name and version.

Options and defaults

Timeouts are in milliseconds.

Option	Default	What it does
`initializeTimeoutMs`	`10000`	How long the client waits for the start-up handshake.
`requestTimeoutMs`	none	With no value, a request waits indefinitely, because a turn can run long.
`shutdownTimeoutMs`	`1000`	How long the shutdown request may take before the close moves on.
`disposeEofGraceMs`	`6000`	How long the runtime may take to finish after its input closes.
`disposeGraceMs`	`3000`	How long it may take to exit after the client sends a stop signal.

The start-up handshake is sent once and reused. It carries the working folder, the provider, the model, the reasoning effort and maxTokens, and the runtime checks that exact route before it accepts a prompt: a provider, model or effort it cannot serve fails the handshake instead of falling back to a default.
env: when you pass it, it replaces the environment completely for the runtime. The client reads it at the moment the runtime starts.

Note

Because env replaces the environment rather than adding to it, list every variable the runtime needs when you use it.

maxTokens: optional. It caps each request the root agent makes, and sub-agents that run in the same process inherit the cap.
reasoningEffort: optional. An omitted effort keeps the model's own default.
provider and model: the route the client asks for. When you leave them out, the client sends its built-in default route.

Send a prompt

Call run() with your prompt. The first call also starts the runtime.
The prompt is accepted into a durable inbox, and the client waits until its message id appears in the receipt before it starts collecting the run's events. The id confirms the prompt was queued; it does not identify a later assistant message, the end of the turn or the prompt's result.
The client collects events until the whole agent next goes idle, and then run() returns a result that separates your session from the wider tree:
- sessionId: the session the run worked in.
- finalResponse: the last committed assistant text of the session.
- events: the events of your session.
- notifications: activity from the wider session tree the run belongs to, sub-agents included. The client tells the two apart along sub-agent lineage.
Each run works in its own session, so session ids differ, while the runtime underneath is reused across runs.
finalResponse is not assigned to the prompt you sent: it is the session's last committed assistant text, and it is empty when there is none.

Read errors and diagnostics

The client throws typed errors: JsonRpcResponseError for an error the other side reported (it keeps the wire code, message and data), RequestTimeoutError for a request that passed its timeout, SdkProtocolError for an answer that did not fit the protocol, and TransportClosedError for using the client after it closed or after the runtime is gone.
A timeout error reads <method> timed out after <ms>ms waiting for <description>; stderr tail: and carries the newest 400 lines of the runtime's error output.
Errors about a runtime that died include the exit code and the same stderr tail.
Three messages name what a start-up or turn answer was missing, quoted here as they appear: initialize returned no server identity:, session/prompt returned no message id: and turn/end carried no reason envelope:. The detail follows the colon.
Keep these details in your logs: the stderr tail and the exit code are what a problem report needs.

Close the client

Call close(), or let await using call it for you when the block ends. close() is safe to call again, and the client starts no new runtime after it: using the client again fails as closed.
It stops the runtime in stages: it sends a shutdown request first (bounded by shutdownTimeoutMs), then closes the runtime's input, then sends a stop signal on systems other than Windows, and finally forces the process to end. It finishes only when the process has exited.
If the process still does not exit, the close fails with runtime process did not exit within <ms>ms after SIGKILL was accepted|refused or SIGKILL failed.
A notification reader that is open when the runtime dies can still read what was already delivered, and then it stops with an error. After close(), notifications that were not delivered yet are dropped.

Questions, answered

What are the default timeouts?

The start-up handshake gets 10 seconds; a request waits indefinitely unless you set requestTimeoutMs; the shutdown request gets 1 second; and the closing stages get 6 seconds after the input closes and 3 seconds after the stop signal.

Can I bound how long the client waits for a turn?

Yes, set requestTimeoutMs. Leaving it out is the default, because a turn can run long. A timeout ends the wait on your side; it does not stop the runtime.

Why must the working folder be an absolute path?

The client resolves the folder before the start-up handshake. An absolute path keeps that resolution final, so the folder cannot be resolved twice.

Which runtime does the client start, and can I point it elsewhere?

By default the client finds the runtime executable itself. Point it at a specific executable when your setup keeps the runtime elsewhere. A runtime of the same version as the client is required either way.

Does `run()` start a new runtime each time?

No. The runtime starts on the first call and is kept for later runs. Each run works in a session of its own, so session ids differ.

How do I know the runtime accepted my prompt?

The client waits for a receipt that carries your prompt's message id before it starts collecting events. That id means the prompt was accepted; it does not point to the answer, the end of the turn or the result.

Is `finalResponse` the reply to my prompt?

Not exactly. It is the last committed assistant text of the session, and it is not assigned to a specific prompt. If the session has not produced an assistant message yet, it is empty.

What happens if the start-up handshake fails?

The client cleans up that attempt and prepares a fresh one, so your next call can try again. If the cleanup fails too, the client reports both failures as one combined error.

Why does an error include an exit code or a stderr tail?

So you can see why the runtime stalled or died. The tail holds the newest 400 lines of the runtime's error output, and the exit code shows how the process ended.

What happens to notifications after `close()` or a crash?

A reader that is open when the runtime dies can still drain what was already delivered, and then it fails. After close(), notifications that were not delivered yet are dropped.

How do I close the client without leaving a stray process?

Call close(). It asks the runtime to shut down and escalates in bounded steps until the process has exited, and calling it again is safe. Only a process that will not exit after the force step makes it fail, with a message that names the wait.