Two kinds of request, and a third that is going away

Two kinds of request, and a third that is going away

A server sometimes needs something only the client side has. The protocol gives it three ways to ask.

Why have sampling at all? A server author may not want to hold a model account. The server says "write me one sentence" and the host's own model does it, under the host's controls, billed to the host. The specification's own migration advice for the deprecated feature is to call a model provider directly from the server instead.

Elicitation has two modes:

• Form mode asks for structured data through a small flat form: a confirmation, a choice, a number, an email.
• URL mode sends the person to a web page outside the client, for anything that must not pass through the client: signing in to a third-party service, entering a payment, pasting a secret.

The person can answer accept, decline (an explicit "no") or cancel (dismissed without choosing). A tool must treat these differently. A decline means "do not ask again for the same thing"; a cancel may be asked later.

How the question travels: multi round-trip requests

In the earlier revisions a server could send a request on the same connection while a tool was running, wait for the answer, and carry on. The new revision removes that: servers do not send requests. Instead, the original call returns early with a result that says "I need input", and the client retries the same call with the answers.

The specification calls this MRTR, multi round-trip requests. It works on three methods only: tools/call, prompts/get and resources/read. The first reply looks like this:

{ "resultType": "input_required",
  "inputRequests": { "confirm": { "method": "elicitation/create", "params": { "message": "...", "requestedSchema": { } } } },
  "requestState": "eyJ...signed token..." }

inputRequests is a map from a key the server chose to a request. The client answers each one and retries the original request with a new JSON-RPC id, an inputResponses map using the same keys, and requestState echoed back exactly as received. The rules the page gives the client are strict: it must not inspect or modify the state, and must not send one if it was not given one. Both fields apply only to that retry. The server must not send a request kind the client did not declare in its capabilities, and the server may not assume the client will ever retry.

Measured in the example, a 250 expense with a person who says yes took 2 requests (ids 1 and 2), 1 prompt and 1 ledger entry. A 50 expense took 1 request and 0 prompts. A decline, a dismissal and a ticked-"no" all ended with 0 entries and a message that told the model what happened and what to do next ("Nothing was submitted. Ask again later if it is still needed.", in the style of module 1).

The client loop is short. It is worth reading, because it is the whole client side of the feature:

def call(self, method, params, extra=None):
    retry = dict(extra or {})
    for _ in range(self.max_rounds):
        reply = self._send(method, {**base, **retry})           # a new request id every time
        res = reply.get("result") or {}
        if res.get("resultType") != "input_required":
            return reply
        answers = {key: self.handler.handle(req) for key, req in res["inputRequests"].items()}
        if any("error" in a for a in answers.values()):
            return {"abandoned": ...}                            # the host refused; stop, do not guess
        retry = {"inputResponses": answers, "requestState": res.get("requestState")}
    return {"abandoned": "too many rounds"}                      # a server must not loop us forever

That last line matters: a server that keeps answering "I need more input" is a loop. The client sets a round limit. In a test, a greedy server that wanted 50 rounds was stopped by a client limit of 3 (it made at most 4 requests).

The tool body runs again: order of effects

Here is the sharpest edge. In the modern era the server holds nothing between rounds. The retry arrives as a fresh request, so the tool body runs again from the top. Anything it did before reaching the question is done again.

def charge_bad(a, ctx):
    s.log.append(("charged", a["amount"]))          # a side effect BEFORE the question
    r = ctx.need("ok", elicit_form(...))            # round 1 stops here; round 2 runs the line above again
    ...

Measured: charge_bad ended with 2 side effects after a confirmed call, and 2 even when the person declined. charge_good, which asks first and acts after the answer, ended with 1.

Anything the tool computed in round 1 and needs in round 2 goes into requestState. In the example, buy_ticket quotes a price once, saves it in the state, and uses it in round 2, so the price the person saw is the price charged. That is useful, and it is also what makes the next section necessary.

requestState is input from an attacker

The state passes through the client. A client you do not control (or a model that can influence it, or a person with a proxy) can read it and change it. The specification says to treat it as attacker-controlled: unless tampering can cause nothing worse than a failure, protect its integrity with an HMAC or authenticated encryption. It also says servers should bind the state to the principal, give it a short lifetime, and bind it to the request (an id or a digest).

The example does exactly that. The token is base64(payload).HMAC-SHA256. The payload carries sub (who), exp (when it stops working), dig (a hash of the method and parameters, ignoring the retry-only fields), a random nonce, and data (what the tool saved).

Measured, each row a separate attempt against the same token:

Now the part people miss. A signed token is not single-use. Presented twice inside its lifetime with no server-side record, it is accepted both times (the amber row in the diagram). The specification says so directly: binding and a short lifetime bound replay but do not prevent it, and any one-time redemption must be enforced on the server. In the example, the voucher tool records the token's nonce: with the record it redeemed once; without it, twice.

And the careless version. With signing turned off, a server that believes whatever state arrives let a client submit a state saying price: 1.0 and the ticket was charged 1.00 instead of 190.00. With signing on, the same request was refused with "malformed state". The attack needed no cleverness; only a server that trusted its own saved number because it had written it earlier.

An invalid state should produce an error that tells the client what to do. The example returns an invalid-params error saying "Invalid requestState: expired. Start the request again without it." (the error code is my choice where the page gave none). The specification says that if a client fails to send information the server needed, the server should ask again instead of erroring, which the example's need() does by construction.