Make sure this mock can receive the participant's callbacks, and report the URL it must use. Call it once before session_create. Under the HTTP transport the receiver is already mounted and this just reports the address; on stdio it binds a listener. Safe to call repeatedly. The address must be reachable from the participant — for a remote participant, set RECEIVER_PUBLIC_URL (or the session's receiver_public_url) to a tunnel address instead.

Close the standalone inbound listener. Only meaningful on the stdio transport; under HTTP the receiver shares this server's port and stops with it, and this explains that rather than failing.

Open a session against a network participant under test and list every flow available for its build. Supply the participant's subscriber URL and whether it is a BAP (buyer app) or BPP (seller app); this server automatically takes the opposite role and answers as that counterparty. Domain, version and use-case must be a published combination — call catalog_list_builds first if unsure, because an unknown use-case is rejected rather than silently returning no flows. The returned callback_url is what the participant must send its callbacks to; give it to them before starting a flow.

Fetch a session by id: the participant under test, the role this server plays against it, the build, and when the session expires. Returns an error result if the session is unknown or has expired.

List every domain, version and use-case published by the ONDC config-service. Call this before session_create when the exact domain code, version or use-case name is uncertain — use-case names are case- and space-sensitive and must match exactly.

List every flow published for the session's build, with the number of steps this server must produce versus the number expected from the participant under test. Use catalog_describe_flow for the full sequence.

The full ordered sequence of one flow. Every step is tagged with an actor: 'mock' means this server must produce it, 'np' means it must arrive from the participant under test. Also lists the inputs each step needs and any parallel or unsolicited steps.

Fetch and cache the mock-runner configuration for a flow — the per-step generation, validation, requirement and save-data logic the workbench uses to drive it. Returns a summary of what each step carries; the configuration itself is held server-side under the returned cache_key for later execution, because it is far too large to read directly.

Open a run of one flow and report what its first step needs. Returns the callback URL the participant under test must be able to reach — every payload this server sends advertises it as bap_uri or bpp_uri, so a participant that cannot reach it will never call back. Fails immediately if the flow has no mock config or any step with no owner, so a flow that cannot be driven is rejected before anything is sent. transaction_id comes back null: it belongs to whoever sends the flow's first action, so when that is the participant it is theirs to choose and does not exist yet. Drive the run by flow_id with flow_proceed and flow_await, which report the id once it exists.

Abandon this run's current attempt and open a fresh one of the same flow, in the same session. Use it when a run has gone wrong and you want another go: a flow's state is derived by replaying what was exchanged, so a NACKed step or an out-of-sequence callback stays part of the history and flow_start would only resume it. Nothing recorded is destroyed — the abandoned attempt keeps its payloads and stays readable with record_get_payload, because a failed attempt is a compliance finding, not a mistake to erase. The new attempt starts unbound: transaction_id comes back null and the next action mints a fresh one. Prefer this over creating a second session; an abandoned session keeps competing for the participant's callbacks on the endpoint every session shares.

Where a run has got to: every step with its status and who owes it, any exchanges that arrived off-sequence, and what the loop needs next. State is derived from the recorded exchanges on every call, so this is always current. Name the run by flow_id (or transaction_id once it has one). Read it whenever you lose track; next says exactly which tool to call.

The loop driver. Takes the next step this mock owns, checks its preconditions, generates its payload from the flow's own mock config, and POSTs it to the participant — then records both the payload and whatever the step saved for later steps. If the step needs values it comes back INPUT_REQUIRED with the declarations; call again with inputs. If the next move is the participant's it comes back WAITING; call flow_await. Pass dry_run: true to generate and inspect a payload without sending it, or trigger_extra to fire a named side-channel step. When a step is blocked because the flow's own config generates a non-compliant payload, payload_overrides patches the offending fields so the run can continue instead of being abandoned. Sending the flow's first action is what mints its transaction_id, which the answer then reports.

Block until something happens, then report it. Two scopes: Name a flow_id (or transaction_id) and it waits on that one run, returning as soon as the participant calls back — pass the seq from your last call as after_seq so nothing is seen twice. When the participant sends the flow's first action this is where you learn the transaction_id, because it was theirs to choose. Name neither and it waits on the whole session: any callback on any run, a step auto-advance sent, a refused call, a form submitted. That is the one to use when you have nothing to do — it needs no seq bookkeeping, and it comes back with runs telling you where every flow stands. Narrow what wakes it with kinds / flow_ids; anything filtered out is still reported, it just does not end the wait. timed_out: true means nothing happened yet — call again. Always prefer this over polling flow_get_status.

Read the form a flow is waiting on. When the participant hosts it, this fetches the page, screens it for active content, and returns its fields ready to fill — then call form_submit. When this mock hosts it, there is nothing to do but wait for the participant, and the answer says so. In a manual-mode session it returns the link to hand to a person instead of the fields. Omit step_key to use whichever form the flow is currently waiting on.

Complete the form step and advance the flow. In llm_auto sessions pass fields (the names come from form_fetch) and this posts them to the participant and reads back the submission id it issues. In manual sessions pass the submission_id the person was given instead. Either way the id is saved where the next step's payload expects it.

Check a protocol payload against the ONDC spec for this session's build, without sending it anywhere. Runs L0 (JSON Schema) and L1 (the spec's contextual rules); every failure comes back with a rule code and a JSONPath. Use it to inspect a body before committing to it, or to understand a refusal. Note that flow_proceed already gates what it sends, so this is not a required step in the loop. A valid verdict only covers the layers listed in checked.

Fetch a payload this session sent or received, by the handle reported in flow_get_status or flow_await. Payload bodies are held server-side and can be very large — a catalog runs to hundreds of kilobytes — so prefer a jsonpath slice (e.g. $.message.catalog.providers[*].id) over the whole body. The result says whether it was truncated.

The values a flow has accumulated across its steps — provider ids, order ids, form submission ids — as the mock config saved them. This is what the next step's payload is generated from, so read it when a step reports missing requirements. Large values (resolved form HTML) are listed under 'omitted' rather than returned; ask for one by name.

Read this session's event journal without consuming it. You do not normally need this: every session-scoped tool result already carries the events since your last call, delivered once each. Reach for it when a result said more was outstanding, when you want to re-read something already delivered, or to recover a delta lost to an error — reading here never moves the delivery cursor, so it cannot consume what piggyback has not yet shown you.

Record your account of an incident this session opened — you will see one as an ISSUE_OPEN event on a tool result. Call it AFTER you have tried to resolve the problem, so you can say how it turned out; report it whether or not you succeeded, because a failure you could not rescue is the more useful of the two. tooling_gap is the most valuable field: it is what changes the tools you are given next time. Do not paste payload values into any field — name the JSONPath instead; values are stripped either way.

Every incident this session has opened, with its derived state and whether it still needs your account. Pass include_body: true to see the fully-redacted report exactly as it would be uploaded — that is the honest answer to a user asking what is being sent about them.