Documentation
¶
Overview ¶
Package roundtrip centralises the allowlist of LLMResponse.Metadata keys that must travel with a conversation Message so the NEXT request can echo them back to the provider verbatim.
Conversation history is provider-neutral, but some providers hand back opaque continuity tokens on an assistant turn and then reject the following request if those tokens are missing:
- Anthropic extended thinking: `thinking_blocks` must be echoed on the assistant turn that precedes a tool_result, or the API returns HTTP 400.
- Gemini thinking: a `thoughtSignature` rides alongside each functionCall part and must be re-emitted with that call, or the API returns HTTP 400.
- OpenAI Responses reasoning: under `store: false` — which is the only mode Nexus uses, because it keeps its own history — each `reasoning` Item in a turn's output carries `encrypted_content`, and every Item must be replayed verbatim on the next request or the model loses its reasoning across a tool round. This one degrades quietly rather than erroring: the request still succeeds, it is just reasoning-blind from the second round on.
The forwarder deliberately does NOT copy the whole metadata map. Engine- internal flags like `_source`, `_structured_output` and `_target_*` are request-scoped routing hints, not message-scoped state, and leaking them into persisted history would make a replayed message look like it came from an internal sub-flow. Only keys a provider identifies as required for round-trip continuity are preserved.
It applies to EVERY history a response is replayed from, not only a persisted one. It was extracted because the same allowlist had been copy-pasted into memory/capped and memory/simple and forgotten entirely in memory/summary_buffer — which silently dropped Anthropic thinking blocks — and it lives under pkg/ because the agent loops that keep their own in-process history (pkg/delegate, plugins/agents/subagent, plugins/agents/planexec, plugins/agents/orchestrator) had forgotten it too: a delegated posture that called one tool and then asked again sent Gemini a functionCall with no thoughtSignature, and every such turn 400'd.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Allowed ¶
Allowed returns the allowlisted subset of a metadata map that arrived from outside the engine. It is ForwardMessageMetadata's inbound twin: same allowlist, applied to a map a client authored rather than one a provider published.
func ForCall ¶
ForCall returns the slice of an allowlisted metadata map that belongs to one tool call, suitable for attaching to that call on a transport whose metadata slot is per-call.
A per-call key is narrowed to the single entry for callID, re-wrapped in a map of the same shape so the value a reader sees is indistinguishable from the unsplit one. A per-message key is carried whole on every call of the turn: MergeCall folds them back with last-write-wins, so repeating the value costs wire bytes and reassembles exactly.
Returns nil when the call has nothing to carry, so a call needing no continuity state serialises without an empty metadata object.
func ForwardMessageMetadata ¶
ForwardMessageMetadata returns the allowlisted subset of an LLMResponse metadata map, suitable for assigning to events.Message.Metadata. Call it wherever an llm.response becomes a history message a later request replays.
Returns nil — not an empty map — when src is nil or carries none of the allowlisted keys, so a message that needs no continuity state serialises without an empty metadata object.
func MergeCall ¶
MergeCall folds one tool call's metadata back into the message-level map ForCall split it out of, and returns the result.
A per-call key is merged ENTRY BY ENTRY, because each call carries only its own and the turn needs all of them; a per-message key is assigned whole, which is the spec's last-write-wins rule and is why ForCall may repeat it. Keys outside the allowlist are dropped: the map arrives from a client on the inbound path, and a replayed message must not be able to introduce engine-internal routing hints by naming them.
Types ¶
This section is empty.