Ordinary MRTR and elicitation

Copy Markdown View Source

The first general MRTR slice supports ordinary tools, resources, and prompts with form/URL elicitation and state-only continuations. It uses public APIs, preserves the synchronous core, and needs no server-owned waiting process. The implementation follows the pinned 2026-07-28 MRTR contract and elicitation contract.

Authoring an interactive operation

  1. Build a bare request with Snodo.Elicitation.form/2 or url/2.
  2. Inspect Snodo.Elicitation.response(context, "choice", request).
  3. On :missing, return {:ok, Snodo.Result.input_required(input_requests: %{"choice" => request})}. That ends this request; it does not suspend it.
  4. On retry, consume the named response, validate any state, then return the feature's normal result. Ignore inputs you do not need and re-request missing answers. Partial answers needed on a later retry belong in protected state.

The component's arguments do not gain hidden keys. Retry data is available as context.input_responses and context.request_state. The raw originating method and params are available as request_method and request_params for binding verification. These are framework-owned fields; middleware should not rewrite them when forwarding context to a handler.

Use example 20 and its shared workflow for a complete, read-only preference flow that works as a tool, resource, and prompt:

mix run examples/20_mrtr_elicitation.exs --check
mix compile --warnings-as-errors
node interop/official_client/check_mrtr.mjs

The Node command needs the pinned dependencies installed with npm ci --ignore-scripts in interop/official_client. It defaults to the dev build; SNODO_EBIN selects a different compiled core. Its five automatic workflows run over stdio and the native HTTP listener without public services, opening a browser, or performing application mutations.

State and effects

Snodo.MRTR.State.seal(data, context, secret: secret, principal: principal) returns an opaque signed token. Use the same options with open/3 on retry. The helper binds the method, salient parameters, explicit principal, and expiry, rejects tampering, and bounds token size. JSON-RPC IDs and top-level retry/metadata fields are excluded from the binding; nested argument fields are not. Map order does not matter, but array order and numeric types do.

The application must provide a cryptographically random secret of at least 32 bytes and select the principal from trusted authentication context. Explicit principal: nil means anonymous. The example uses a process-lifetime random secret for anonymous loopback use; distributed deployments need shared secret management. The default TTL is 300 seconds, capped at 900 seconds.

Tokens are readable, not encrypted. Do not put secrets in them. They can be reused until expiry, so one-time operations need application-owned replay tracking and idempotency. Authorization must still be checked on every request. Do not perform a non-idempotent effect before returning input-required and assume that the client will retry exactly once—or at all.

Admission, errors, and composition

The dialect checks outgoing input-required placement and current peer capabilities after middleware returns. Only tools/call, resources/read, and prompts/get support this core result variant. The raw wire escape hatch does not bypass these checks. Missing mode capability returns -32021 with requiredCapabilities; malformed retry envelopes return -32602 before the component runs. Unsupported result placement is a server error.

The new optional dialect validate_result/3 hook does not change custom dialects that omit it. Extension middleware runs anew on every retry and cannot enlarge the original client's capabilities by passing an altered handler context. Custom extension routes still own their semantics; embedded methods are not top-level RPCs or new extension route registrations.

Typed callback failures ({:error, %Snodo.Error{}}) now retain their documented JSON-RPC error semantics for tools as well as resources/prompts. Previously the tool router incorrectly converted them into isError results. Explicit Snodo.Result.error/2 and legacy untyped tool failures remain tool error results. This distinction matters for invalid elicitation answers and failed state verification.

Input-required responses bypass final structured-output validation and resource cache decoration. Final results still use the normal schema/content validation. No executor slot is retained after the response. Elicitation action: "cancel" is a returned user choice, separate from cancelling an active protocol request.

Deliberate limits

  • This slice supports elicitation and state-only continuation; deprecated roots and sampling input requests remain unsupported, as does extension-owned embedded request registration.
  • Form schemas use the restricted flat primitive/enum subset, not arbitrary JSON Schema. Unsupported keywords are rejected. Formats have documented syntactic checks, not full RFC or service validation. The optional JSV backend now provides general tool schema validation; it does not widen this protocol-specific form subset. See the application stack.
  • Form mode must not collect credentials. URL helpers accept HTTP(S) navigation only. URL acceptance indicates consent, not completion of an external action; applications must check that independently.
  • Ordinary MRTR is not automatically converted into Tasks mid-flight input. Finish synchronous MRTR before creating a task, or use Tasks.await_input/3 inside a task. A terminal task result cannot be another ordinary continuation.
  • The pinned TypeScript client rejects empty inputRequests without a state string, despite the schema allowing an empty map. Core literal tests preserve the schema's shape; examples use nonempty input or state-only responses.
  • Official-client acceptance is not a fresh external conformance-runner score, full wire-schema validation, or evidence for every MCP host.

Initial MRTR checkpoint — 2026-09-14

Verified on Elixir 1.20.4 / OTP 29.0.6 with ERL_FLAGS='+S 4:4':

  • Core mix test --warnings-as-errors: 272 passing (one doctest, 271 tests).
  • mix snodo.contract: 107 passing tests, 29 evidence groups.
  • Core formatting, strict Credo, dev warnings-as-errors compilation, and dev Dialyzer: passed; zero Dialyzer errors/skips and no new suppressions.
  • Tasks mix test --warnings-as-errors: 85 passing, including five new ordinary-MRTR/terminal-task boundary tests.
  • Tasks mix tasks.contract: 71 passing tests, 10 evidence groups; test-environment formatting and strict Credo passed with no issues.
  • Existing Hex.pm application suite: 130 passing. Its separate pinned official-client acceptance also still passes over stdio and HTTP.
  • Example 20 standalone --check: passed. It is registered in the default nineteen-example gate; the entire example set was not rerun in this slice.
  • Official TypeScript client 2.0.0 MRTR check: both stdio and native HTTP passed, each with five automatic workflows, eight elicitation callbacks, and fifteen operation requests. Fresh IDs, state replacement/discarding, changed-argument rejection, and URL consent semantics are asserted.

The initial implementation did not rerun the external conformance runner, unchanged storage-adapter suites, or Tasks/storage-adapter development Dialyzer. The subsequent external fixture close-out passed 31/37 required scenarios, including nine newly exercised ordinary MRTR scenarios. The later progress slice raises the current score to 32/37; the current aggregate evidence is in target application findings. See conformance results. The official-client and frozen external regression checks are now wired into CI; the checked-in workflow is policy until its remote job actually runs.

The literal acceptance suite covers all three feature families over direct, stdio, and HTTP adapter boundaries; the independent client also uses a real HTTP listener. Coverage includes multiple inputs, partial answers, repeated rounds, extra IDs, declined/cancelled input, malformed responses, tampered state, capability changes, final-output validation, and extension guards.