roundtrip

package
v0.31.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 0 Imported by: 0

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

func Allowed(src map[string]any) map[string]any

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

func ForCall(src map[string]any, callID string) map[string]any

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

func ForwardMessageMetadata(src map[string]any) map[string]any

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

func MergeCall(dst map[string]any, callMeta map[string]any) map[string]any

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL