An optional declared parameter that state cannot fill is dropped silently

[ciaransweet]

An optional declared parameter that session state cannot fill is dropped silently. The tool runs without it and nothing — not the model, not the transcript, not the host — records that a value was expected and missing.

Where this came from

ECMWF's cds toolset declares a bounding box:

async def submit_request(
    dataset: str,
    request: dict[str, Any],
    area: Annotated[list[float] | None, Kind(BBOX, model_generatable=False)] = None,
) -> ...

get_aoi publishes gazet/bbox as a geo.BoundingBox; the runtime injects it. Working as intended, a geometry reaches the request without ever entering the model's context.

A model that batches get_aoi and submit_request into one assistant message breaks it. LangGraph runs both in a single super-step against state as it stood at the start, so submit_request cannot see the publication happening beside it. area is absent, and the request submits over the whole dataset instead of over Copenhagen.

No error. CDS accepts a dataset-wide request, queues it, returns a job id. The geometry never appears in the conversation by design, so its absence does not either. The user gets data — the wrong data, at a much larger size, for somewhere they did not ask about.

Why

injection.py:

found = resolve(declaration, injected_state, schemas[parameter])
if found is not None:
    arguments[parameter] = entry.get("value")      # inject
elif declaration.get("required", True):
    raise StateRefusal(...)                        # refuse
# implicit third branch: proceed without it, silently

And required is not something anyone chose. From declarations.py:

# required is read from the tool's own input schema rather than declared
_declaration(parameter, marker, required=parameter not in optional)

area: ... = None has a default, so it is not in the schema's required list, so required=False. The safety behaviour is coupled to an unrelated Python idiom — the = None you have to write anyway, because the model is not supplying this parameter.

required=True is not the fix. Optional is correct here: dataset-wide requests are legitimate, and the publishing toolset may not be connected at all.

Proposed fix: say so, do not refuse

bind_injected already computes, per parameter, which connected tools publish that kind:

producers = {item["parameter"]: ... published.get(wants(item), []) for item in declarations}

That is exactly the missing distinction, and it is already in scope:

• falsy — nothing publishes this kind. Absence is expected. Stay silent.
• truthy — something publishes it and state is empty anyway. Suspicious.

So make the third branch explicit:

elif publishers := producers[parameter]:
    omitted[parameter] = Omission(kind=wants(declaration), publishers=publishers)

and surface it through machinery that already exists:

• to the model, as a third breadcrumb beside [state used: …] and [state updated: …]:
  [state missing: area — geo.BoundingBox, published by get_aoi, not yet in session state]
• to a host, as a state.omitted activity beside state.consumed / state.published.

The breadcrumb is the point: it lands in the transcript in the same turn, so the model can resubmit with the AOI or tell the user the request went dataset-wide. Same recovery shape as #74's refusal-as-ToolMessage.

A refusal instead would be worse — on turn one a legitimate dataset-wide request would be blocked, and the model has no escape hatch, since model_generatable=False prunes the parameter from its schema entirely. It cannot say "I meant the whole domain". Annotation is silent in exactly the case that is legitimate.

Notes

• Omission should be a sibling of Receipt, not a Receipt — there is no key, nothing was read, and receipts_of filters on key being truthy.
• _residue rewrites the artifact after capture and carries receipts through explicitly. Omissions need the same, or they are lost between injection and the message. Worth a test that asserts the omission survives capture, not just injection.
• Adding state.omitted changes the documented activity vocabulary, so CONSUMING.md, SESSION-STATE.md and the example README need a line.
• This makes the mistake visible, it does not prevent it. The batched call still submits without the area. Preventing it means not running a consumer and its publisher in the same super-step, which is a graph-level change and a separate issue.

[ciaransweet]

Generated via Claude after some back and forth.

I'm not sure if this is worth addressing but wanted it to live somewhere for now.

We'd get this issue without Kinds anyway, so it's a bit of a problematic one.

[ciaransweet]

Proposed addition: stop the batch causing it in the first place

The fix above makes the omission visible. It does not stop the request going out wrong. Worth doing alongside it, because the batched publisher/consumer pair is the case that produces the bad request, and it is preventable.

ToolCallRequest carries state, so from inside awrap_tool_call the middleware can reach the assistant message that issued the batch — and therefore see a call's siblings. That is enough to do this where we already are, with no graph surgery.

Defer a call whose publisher is in its own batch. StateCaptureMiddleware already knows published (kind → publishing tools) and each tool's declarations. If the batch contains a tool publishing kind K and this tool declares K, do not run it — return a ToolMessage(status="error"):

deferred: get_aoi in this same step publishes what area needs. Call submit_request again once it has run.

The model retries it alone in the next step and it succeeds, because the publisher's write has merged by then. Same recovery shape as #74's refusal-as-result, which is proven end to end. It fires only on a genuine publisher/consumer pair in one batch, so nothing else is slowed down and ordinary parallel calls are untouched.

Alternatives considered

• parallel_tool_calls=False on the model binding — one line, and it does fix it, but it disables all batching including the majority that is harmless and faster. Provider-dependent too.
• Execute the batch in dependency order — topologically sort the calls, run publishers first, thread their writes into the consumers' injected_state before the super-step merges. This is the real cure, and the only option where the batch still completes in one step. But it needs a batch-level seam, likely a custom ToolNode rather than middleware, and it takes ownership of ordering semantics away from LangGraph. Worth recording as the follow-up, not the first attempt.

Why this does not replace the fix above

Deferral only helps when the publisher is in the batch. It does nothing for the case where the model simply never called it — no AOI tool anywhere in the turn, area unfilled, request goes dataset-wide. That case still needs the omission to be recorded and said out loud.

The two are complementary: deferral removes the common cause, the breadcrumb catches the rest.