openaiwire

package
v0.6.1 Latest Latest
Warning

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

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

Documentation

Overview

Package openaiwire holds the OpenAI-shaped chat-completions wire format shared by every native adapter whose provider speaks that dialect (kimi, openrouter): the request and response structs, message and tool conversion, stop-reason mapping, the SSE emitter and the authenticated HTTP client. Provider-specific extensions (kimi's partial/name and reasoning_effort, openrouter's reasoning object and reasoning_details) stay in the adapter that needs them; this package only knows the shape every OpenAI-compatible provider shares.

Index

Constants

View Source
const (

	// MaxErrorText bounds endpoint-chosen text echoed into an error, which
	// may reach logs or clients.
	MaxErrorText = 512
)

Limits on what an endpoint can make this process hold or echo. A user-supplied endpoint can send anything, and one tenant must not be able to exhaust a host shared with others.

Variables

This section is empty.

Functions

func ArgsString

func ArgsString(args json.RawMessage) string

ArgsString renders tool-call args (json.RawMessage) as the OpenAI arguments string. Empty args become "{}" so the wire message stays valid.

func AssembleMessage

func AssembleMessage(reasoning, content string, calls []ToolCall, finish string) ac.Message

AssembleMessage builds an assistant message from its parts, in the order the agent loop expects (thinking, text, tool calls). Shared by the non-stream path and the stream's terminal message so both produce identical structure. The adapter adds any extra metadata (such as openrouter's reasoning_details echo) to the returned message afterwards.

func ConvertMessages

func ConvertMessages[M any](msgs []ac.Message, assistant func(ac.Message) M, plain func(role, content, toolCallID string) M) []M

ConvertMessages maps agentcore messages to the provider's wire message type M, delegating construction to two adapter-supplied constructors: assistant builds the (provider-specific) assistant message, and plain builds every other role from a role, its text content and, for a tool result, the tool_call_id it answers. The system prompt stays inline as a system-role message and tool results are their own "tool" role (not a user message), matching the OpenAI shape every such provider speaks.

func MapStopReason

func MapStopReason(reason string) ac.StopReason

MapStopReason maps an OpenAI finish_reason to an agentcore StopReason.

func RawArgs

func RawArgs(s string) json.RawMessage

RawArgs is the inverse: a wire arguments string to json.RawMessage, defaulting empty to "{}" so the enclosing message stays JSON-serializable.

func ReadSSE

func ReadSSE(r io.Reader, onData func(data string) (stop bool, err error)) (done bool, err error)

ReadSSE reads r line by line to completion, extracting each "data:" frame's payload and invoking onData with it. It stops at a data frame of "[DONE]" or when onData reports stop=true, and returns any error onData reports or any read error other than a clean EOF (an SSE body ends without a trailing frame, so that is not itself an error).

done reports whether the stream terminated on an explicit "[DONE]" frame. A false done with a nil error means the body simply ended: the response may be truncated mid message, so the caller must not treat what it accumulated as a complete turn unless a finish_reason arrived.

A line longer than maxSSELine fails the stream: no real chunk is that big, and buffering one without limit lets an endpoint exhaust memory.

func Sanitize added in v0.6.0

func Sanitize(s string, max int) string

Sanitize makes endpoint-chosen text safe to put in an error: newlines and tabs become spaces, other control characters (terminal escapes) are dropped, and the result is cut to max bytes on a rune boundary.

func Send

func Send(ctx context.Context, out chan<- ac.StreamEvent, ev ac.StreamEvent) bool

Send delivers ev on out unless ctx is already done, reporting whether the send happened. Every producer send goes through this: a consumer that stops reading must not pin the producer goroutine or the HTTP body it holds for the life of the process.

Types

type Client

type Client struct {
	HTTP     *http.Client
	BaseURL  string
	APIKey   string
	Provider string
	Headers  map[string]string
	// StreamHTTP sends streaming requests. It carries no overall timeout: a
	// long generation is legitimate, and a stalled one is caught by StreamIdle
	// instead. Falls back to HTTP when nil.
	StreamHTTP *http.Client
	// StreamIdle aborts a stream whose body has produced nothing for this
	// long. Zero disables the watchdog.
	StreamIdle time.Duration
}

Client is the shared authenticated JSON-over-HTTP client both adapters use to talk to their OpenAI-shaped chat-completions endpoint. Provider names the source in every error message; Headers carries any extra headers a provider always sends (OpenRouter's HTTP-Referer/X-Title attribution), applied to every request alongside the bearer token.

Every request retries the transient statuses (429 and 5xx) so a coding agent's long run is not ended by one throttled call, and every failure is classified: a provider message about the context window comes back as agentcore's ContextOverflowError so the agent loop compacts rather than aborts.

func (*Client) NewRequest

func (c *Client) NewRequest(ctx context.Context, path string, body []byte, apiKeyOverride string) (*http.Request, error)

NewRequest builds an authenticated JSON POST, with any configured extra headers set. apiKeyOverride overrides the client's APIKey when non-empty.

func (*Client) Post

func (c *Client) Post(ctx context.Context, path string, body any, apiKeyOverride string) ([]byte, error)

Post marshals body, sends it to path and returns the response bytes, failing on a non-200 with the response text. apiKeyOverride overrides the client's APIKey when non-empty (per-call key rotation).

func (*Client) Stream

func (c *Client) Stream(ctx context.Context, path string, body []byte, apiKeyOverride string) (io.ReadCloser, error)

Stream sends body to path as an SSE request and returns the live body for the caller to read to completion and close. Retries apply to the initial status only: once a byte of the body has been consumed the turn is under way, and resending it would duplicate whatever the model already emitted. The returned reader enforces StreamIdle, so a body that goes quiet fails with an error wrapping agentcore.ErrProviderStreamIdle.

type Delta

type Delta struct {
	Content   string
	Reasoning string
	ToolCalls []StreamToolCall
}

Delta is one incremental update extracted from a provider's own SSE chunk type. The adapter decodes its chunk (with its own quirks: kimi's reasoning_content, openrouter's reasoning/reasoning_details) and hands Emitter.Handle a Delta so accumulation and event framing stay in one place.

type Emitter

type Emitter struct {
	Out chan<- ac.StreamEvent
	// contains filtered or unexported fields
}

Emitter accumulates streamed content and frames it as agentcore StreamEvents. It tracks whether the thinking/text blocks are open and builds tool calls by provider index, assigning each block a stable agentcore content index. The adapter decodes its own chunk type and feeds this Emitter one Delta per choice via Handle.

func NewEmitter

func NewEmitter(ctx context.Context, out chan<- ac.StreamEvent) *Emitter

NewEmitter builds an Emitter that sends its framed StreamEvents on out. ctx is the request context: once it is done the Emitter stops sending and reports Aborted, so the adapter can drop the rest of the stream.

func (*Emitter) Aborted

func (e *Emitter) Aborted() bool

Aborted reports whether a send was abandoned because the request context ended. The adapter checks it before sending its own terminal events.

func (*Emitter) Finish

func (e *Emitter) Finish() string

Finish returns the finish_reason seen so far, empty when the provider has not reported one. An empty Finish once the body has ended means the stream was cut short, not that the model stopped.

func (*Emitter) Flush

func (e *Emitter) Flush(final func(reasoning, content string, calls []ToolCall, finish string) ac.Message) ac.Message

Flush closes any open blocks, emits a tool-call-end (with the completed call) for each streamed tool call and returns the terminal message built by final from the accumulated reasoning, text, tool calls and finish reason. The caller decorates the result (Usage, provider-specific metadata) and sends it as the terminal Done event; usage and mid-stream errors are the adapter's concern, not this package's. Only a stream that actually finished may be flushed: a truncated one has no complete tool call or message to report.

func (*Emitter) Handle

func (e *Emitter) Handle(d Delta, finish string)

Handle processes one delta: reasoning first (thinking), then text, then tool calls, recording the finish reason when present. The adapter calls Handle once per choice in its chunk (and, when a provider can attach more than one reasoning fragment to a single chunk, once more per fragment).

type Func

type Func struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

Func is a tool call's function name and arguments (a JSON-encoded string, not a raw object, per the OpenAI wire format).

type Message

type Message struct {
	Role       string     `json:"role"`
	Content    string     `json:"content,omitempty"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`
}

Message is the OpenAI-format chat message shape common to every adapter: a role, its content, any tool calls an assistant message carries and an optional tool_call_id for tool-role messages. Provider extensions (kimi's partial/name, openrouter's reasoning/reasoning_details) live in the adapter's own message type, which embeds this one.

type Request

type Request[M any] struct {
	Model      string `json:"model"`
	Messages   []M    `json:"messages"`
	Tools      []Tool `json:"tools,omitempty"`
	ToolChoice any    `json:"tool_choice,omitempty"`
	// ResponseFormat carries agentcore's per-call response format through as
	// is: *agentcore.ResponseFormat already marshals to the OpenAI shape.
	// Leave it nil to keep it off the wire; a typed nil pointer would encode
	// as a JSON null and some providers reject that.
	ResponseFormat any      `json:"response_format,omitempty"`
	Stream         bool     `json:"stream"`
	MaxTokens      int      `json:"max_completion_tokens,omitempty"`
	Temperature    *float64 `json:"temperature,omitempty"`
	TopP           *float64 `json:"top_p,omitempty"`
}

Request is the shared OpenAI-format chat-completions request body. M is the provider's own message type, which embeds Message and adds its own fields, so Messages can carry provider extensions without this package knowing them. An adapter that needs a different wire name for a shared field (kimi sends max_completion_tokens, openrouter sends max_tokens) redeclares that field in its own request struct. The redeclaration shadows the promoted one for Go field access only: encoding/json keys on the JSON name, so a differently tagged promoted field is still a candidate. It works because nothing ever assigns the promoted field, and its omitempty keeps the zero value off the wire, leaving only the adapter's own tag.

type StreamToolCall

type StreamToolCall struct {
	Index    int    `json:"index"`
	ID       string `json:"id"`
	Type     string `json:"type"`
	Function Func   `json:"function"`
}

StreamToolCall is one tool_call delta fragment from an SSE chunk. Index identifies which call the fragment belongs to: id and name arrive on the first fragment for that index, arguments stream across later ones.

type Tool

type Tool struct {
	Type     string   `json:"type"`
	Function ToolFunc `json:"function"`
}

Tool is an OpenAI-format function tool declaration.

func ConvertTools

func ConvertTools(tools []ac.ToolSpec) []Tool

ConvertTools maps agentcore tool specs to OpenAI-format function tools, skipping any tool with an empty name.

type ToolCall

type ToolCall struct {
	ID       string `json:"id"`
	Type     string `json:"type"`
	Function Func   `json:"function"`
}

ToolCall is a completed OpenAI-format tool call, on an assistant message or a non-stream response.

func ToolCallsFrom

func ToolCallsFrom(m ac.Message) []ToolCall

ToolCallsFrom renders an agentcore message's tool calls as wire tool calls, so every agentcore tool call round-trips to a wire tool_call and a replayed transcript keeps an exact tool-call set. Both adapters call this from their own assistant-message constructor.

type ToolFunc

type ToolFunc struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Parameters  any    `json:"parameters,omitempty"`
	Strict      *bool  `json:"strict,omitempty"`
}

ToolFunc is a tool declaration's function shape.

Jump to

Keyboard shortcuts

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