The mock LLM server

The mock LLM server is a small standalone process that stands in for a model provider, so tests and demos can exercise provider failures and successes without a provider key. It serves the messages endpoint that model adapters speak, and each accepted request plays the next behaviour from a script you pass on the command line. The server never retries a request and never interprets recovery policy of its own. To choose between the test benches, see Testing tiers.

Run the server

Run the standalone process from your checkout of the Oda source:

pnpm run mock:llm \
  --port 8000 \
  --api-key mock-key \
  --sequence partial_disconnect,success \
  --partial-text "discard this half"

No installable binary. The server runs from the project checkout; there is nothing to install.
Defaults. It listens on 127.0.0.1 port 8000 unless you change --host or --port. --sequence is required and has no default.
Standard output is JSONL. Every line is one JSON object:
- a ready record first, with the /v1 base URL and the seed used for random selection:

json

{"type":"ready","baseURL":"http://127.0.0.1:8000/v1","randomSeed":42}

then a request record and a result record for every accepted request; both name the attempt number, the scripted entry and the concrete behaviour it resolved to (the two differ for random), and the result adds the outcome and how many stream chunks were sent;
with connection_refused first, an unavailable record is printed before the listener delay, carrying the base URL and the delay.
Bad options exit non-zero. A bad option prints its message and the usage text to standard error and exits with code 1. --help prints the usage text.

Script the behaviours

One entry per request. --sequence is a comma-separated first-in, first-out list; each accepted request consumes exactly one entry, in arrival order.
Exhaustion is loud. When the list runs out, the next request gets a structured HTTP 500 with mock script exhausted. --repeat-last reuses the final entry instead.
connection_refused is special. It is accepted only as the first entry and is not a request behaviour: it delays binding the port so that requests during --listen-delay-ms (default 750 ms) get a real TCP refusal. With it, --port is required and must be nonzero. The remaining entries begin once the listener is up.

The catalogue of 24 behaviours:

Behaviour	What the wire does
`success`	Streams a complete text response; stop reason `end_turn`.
`slow_success`	Like `success`, with `--chunk-delay-ms` between text chunks.
`reasoning_success`	Streams a reasoning block first, then a complete text response.
`tool_call_success`	Streams a tool call, using `--tool-name` and `--tool-arguments`; stop reason `tool_use`.
`max_tokens`	Streams a complete text response; stop reason `max_tokens`.
`empty`	Sends a valid content-less completion: a stop with no text, then the closing `message_stop` marker.
`empty_body`	Ends cleanly without any events or the closing marker.
`stream_eof`	Sends the message start, then ends without the closing marker.
`partial_eof`	Sends text from `--partial-text`, then ends without the closing marker.
`partial_disconnect`	Sends text deltas, then resets the connection.
`connection_reset`	Destroys the socket before any HTTP headers are sent.
`stream_disconnect`	Sends SSE headers, then resets the connection before the first event.
`stall`	Sends SSE headers and stays idle until the client or the server closes the connection.
`malformed_json`	Sends a data event that is not valid JSON.
`malformed_event`	Sends a chunk with an invalid shape.
`wrong_content_type`	Sends a valid SSE body under `application/json`.
`rate_limit`	Returns a 429 error with a `Retry-After` header.
`server_error`	Returns a 500 error.
`service_unavailable`	Returns a 503 error.
`auth_error`	Returns a 401 authentication error.
`invalid_request`	Returns a 400 invalid-request error.
`context_overflow`	Returns a 400 error with the context-length-exceeded code.
`quota_exceeded`	Returns a 429 insufficient-quota error.
`random`	Draws the request's concrete behaviour from seeded weights.

Random mode

Seeded selection. A random entry resolves at request time through a seeded draw over relative weights, so a run is reproducible from its printed seed. Omitting --seed generates one and prints it in the ready record.
Weights. --random-weights takes behavior=weight entries with non-negative relative weights and requires at least one positive entry; the entries must name concrete behaviours (random itself is not allowed).
The default profile is stress, not reality. Without --random-weights, random uses a success-heavy default (success 48, slow_success 10, partial_disconnect 10, connection_reset 5, stream_disconnect 5, empty 5, rate_limit 5, server_error 4, max_tokens 2, stall 2, service_unavailable 2, partial_eof 1, malformed_json 1). It is test pressure, not an estimate of how often these failures happen in production.
stall needs a client-side timeout. When the weights can produce stall, give the client under test a short stream-idle timeout so the scenario ends promptly.
--seed and --random-weights are refused when the sequence contains no random.

Timing, content and the key

Flag	Default	What it controls
`--success-text`	`mock response recovered`	Text of a complete response.
`--partial-text`	`discarded partial response`	Text sent before a partial EOF or a reset.
`--reasoning-text`	`mock reasoning`	Reasoning block of `reasoning_success`.
`--chunk-size`	8	Unicode code points per stream delta.
`--chunk-delay-ms`	25	Delay between chunks in `slow_success`.
`--disconnect-delay-ms`	10	Delay before a forced disconnect.
`--retry-after-ms`	1000	Provider retry delay; the `Retry-After` header rounds up to whole seconds.
`--request-id`	(none)	Value returned as `x-request-id` on error responses.
`--tool-name`	`mock_tool`	Tool name used by `tool_call_success`.
`--tool-arguments`	`{"value":"mock"}`	Raw JSON arguments used by `tool_call_success`.
`--api-key`	(none)	When set, requests must carry this exact value in `x-api-key`; without it, any token is accepted.

Which requests consume the script

One rule. Only a POST whose path ends in /v1/messages (a gateway prefix before it is fine), carrying a matching key when one is configured and a body that parses as JSON, consumes the script. An empty body is accepted.
Everything else is an ordinary 4xx, and the sequence does not move:

Refusal	Answer
Wrong method	405 with `allow: POST`
Path that does not end in `/v1/messages`	404
`x-api-key` does not match the configured key	401 `invalid mock API key`
Body that does not parse as JSON	400 `request body must be valid JSON`

A misconfigured client can burn retries this way without advancing the sequence.

The structured errors a script can return

Message	Status	Code
`mock rate limit`	429	`rate_limit`, with `Retry-After`
`mock server error`	500	`server_error`
`mock service unavailable`	503	`service_unavailable`
`mock authentication failed`	401	`invalid_api_key`
`mock invalid request`	400	`invalid_request`
`mock input exceeds the model context window`	400	`context_length_exceeded`
`mock insufficient quota`	429	`insufficient_quota`
`mock script exhausted`	500	`MOCK_SCRIPT_EXHAUSTED`
`mock server handler failed`	500	`MOCK_HANDLER_FAILED`

An error response counts as a completed outcome for the request record. When --request-id is set, these responses carry it as x-request-id; only rate_limit adds Retry-After.

How a request ends

Each request record carries one outcome:

completed: the behaviour ran to its end, including error responses.
reset: a disconnect behaviour destroyed the connection.
stalled: the stall behaviour is holding the connection open.
client_closed: the client went away before the response finished.
server_error: the handler itself failed.

Limits

Arrival order is shared. Request scripts are consumed in arrival order, and concurrent callers share one cursor. For deterministic per-session faults, run a separate server instance per session or test.
The seed is your reproducibility handle. Record the seed from the ready record; the same seed and weights replay the same draw sequence.
A true connection refusal is a listener phase. The --listen-delay-ms window must overlap the client's attempt, and random cannot draw connection_refused because a bound listener cannot refuse.

For the keyless counterpart that replays recorded model streams instead of faulting, see Session replay fixtures.

Questions, answered

Why did my request get a 4xx and the sequence not advance?

Invalid requests never consume a script entry. Only a POST ending in /v1/messages, with a matching key when one is configured and a JSON body, advances the sequence; a wrong method, path, key or body gets its ordinary 4xx first.

The server answered `mock script exhausted`. What should I do?

The sequence ran out. Lengthen --sequence, or pass --repeat-last so the final entry is reused for every further request.

How do I make a random run reproducible?

Pass a fixed --seed, or record the generated seed from the ready record, together with your --random-weights. The same seed and weights replay the same sequence of draws.

Can two tests share one mock server instance?

Not safely for deterministic faults: scripts are consumed in arrival order and concurrent callers share one cursor. Run a separate instance per test or session.

What does `connection_refused` require?

It must be the first sequence entry, the port must be explicit and nonzero, and its window is --listen-delay-ms (default 750 ms). During that window requests get a real TCP refusal; afterwards the remaining entries play in order.

Why did `empty_body` end without the closing marker?

That is its purpose: empty_body, stream_eof and partial_eof deliberately omit the closing stream marker so clients that require it fail. Use empty when you want a well-formed, content-less completion.

Which failures add a `Retry-After` header?

Only rate_limit does, as a whole number of seconds rounded up from --retry-after-ms (default 1000 ms, so one second). Other errors never add the header.

Does the API key have to match exactly?

Only when you start the server with --api-key. Then every request must carry that exact value in x-api-key, or it gets 401 invalid mock API key. Without --api-key, any token is accepted.

What happens when my client disconnects mid-stream?

The request record settles as client_closed, and the server keeps serving other requests. Closing the server stops it accepting requests and terminates stalled connections.

Why is `--listen-delay-ms` refused with an ordinary sequence?

The flag only applies to the pre-listen refusal phase, so it requires connection_refused as the first entry. With an ordinary sequence there is no unavailable window to configure.