executor

package
v8.0.75 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 10 Imported by: 11

Documentation

Index

Constants

View Source
const (
	// PinnedAuthMetadataKey locks execution to a specific auth ID.
	PinnedAuthMetadataKey = "pinned_auth_id"
	// ExcludedAuthIDsMetadataKey excludes specific auth IDs from selection for the current attempt.
	ExcludedAuthIDsMetadataKey = "excluded_auth_ids"
	// SelectionIDMetadataKey stores the per-selection ID generated for a plugin scheduler pick.
	SelectionIDMetadataKey = "selection_id"
	// SelectedAuthMetadataKey stores the auth ID selected by the scheduler.
	SelectedAuthMetadataKey = "selected_auth_id"
	// SelectedAuthCallbackMetadataKey carries an optional callback invoked with the selected auth ID.
	SelectedAuthCallbackMetadataKey = "selected_auth_callback"
	// SelectedAuthIndexMetadataKey stores the stable index of the auth selected by the scheduler.
	SelectedAuthIndexMetadataKey = "selected_auth_index"
	// SelectedAuthIndexCallbackMetadataKey carries an optional callback invoked with the selected auth index.
	SelectedAuthIndexCallbackMetadataKey = "selected_auth_index_callback"
	// FinalizedResponseFormatCallbackMetadataKey carries an optional callback invoked with the effective response_format after payload rules.
	FinalizedResponseFormatCallbackMetadataKey = "finalized_response_format_callback"
	// ExecutionSessionMetadataKey identifies a long-lived downstream execution session.
	ExecutionSessionMetadataKey = "execution_session_id"
	// DerivedSessionIDMetadataKey stores a stable session identity inferred from request context.
	// It may be used to derive a provider session identity.
	DerivedSessionIDMetadataKey = "derived_session_id"
	// LCPAffinitySessionIDMetadataKey stores an LCP-only routing identity. Executors
	// must not use it as a provider conversation or execution-session identity. The
	// current phase also keeps it out of SessionTree topology until downstream wiring exists.
	LCPAffinitySessionIDMetadataKey = "lcp_affinity_session_id"
	// CanonicalSessionIDMetadataKey stores the single unified session identity reconciled
	// across explicit harness headers, body fields, execution sessions, LCP inference,
	// and fallback context derivation for unified debugging and cross-subsystem tracing.
	CanonicalSessionIDMetadataKey = "canonical_session_id"
	// ParentSessionIDMetadataKey stores the parent session identity for hierarchical sessions and forks.
	// For top-level Merkle LCP forks, it represents the deterministic Merkle prefix hash at the divergence point.
	ParentSessionIDMetadataKey = "parent_session_id"
	// IsForkMetadataKey indicates whether the request represents a conversational branch or fork.
	IsForkMetadataKey = "is_fork"
	// IsCompactionMetadataKey indicates whether the request represents a context compaction continuation.
	IsCompactionMetadataKey = "is_compaction"
	// NodeKindMetadataKey indicates the session DAG topology kind ("compaction", "fork", or "trunk").
	NodeKindMetadataKey = "node_kind"
	// LCPTailFingerprintsMetadataKey stores the actual trailing turn fingerprints for context compaction matching.
	LCPTailFingerprintsMetadataKey = "lcp_tail_fingerprints"
	// LCPEnvironmentDigestMetadataKey stores the environment digest across all system and developer instructions.
	LCPEnvironmentDigestMetadataKey = "lcp_environment_digest"
	// LCPAccessGenerationMetadataKey stores the monotonic access generation when an LCP entry was touched or bound.
	LCPAccessGenerationMetadataKey = "lcp_access_generation"
	// LCPFingerprintMetadataKey stores bounded request-scoped turn fingerprints so
	// SessionAffinitySelector.OnResult can avoid reparsing the original payload.
	LCPFingerprintMetadataKey = "lcp_fingerprints"
	// LCPMinPrefixLengthMetadataKey stores the minimum eligible prefix boundary for
	// the bounded LCP fingerprint sequence.
	LCPMinPrefixLengthMetadataKey = "lcp_min_prefix_length"
	// CallerScopeMetadataKey isolates inferred session identities between downstream callers.
	CallerScopeMetadataKey = "caller_scope"
	// SessionAffinityProviderMetadataKey carries the affinity selection namespace
	// (provider string, e.g. the literal "mixed" pool key) used by SessionAffinitySelector.Pick,
	// so OnResult keys the session cache identically to how selection read it.
	SessionAffinityProviderMetadataKey = "session_affinity_provider"
	// SessionAffinityModelMetadataKey carries the model used during session affinity selection.
	SessionAffinityModelMetadataKey = "session_affinity_model"
)
View Source
const AuthSelectionModelMetadataKey = "auth_selection_model"

AuthSelectionModelMetadataKey overrides the model used only for auth selection.

View Source
const DisallowFreeAuthMetadataKey = "disallow_free_auth"

DisallowFreeAuthMetadataKey instructs auth selection to skip known free-tier credentials.

View Source
const GenerateMetadataKey = "generate"

GenerateMetadataKey stores whether the client requested actual generation for usage logs. Missing or true means generation is enabled; only an explicit false disables generation.

View Source
const ReasoningEffortMetadataKey = "reasoning_effort"

ReasoningEffortMetadataKey stores the client-requested reasoning effort for usage logs.

View Source
const RequestPathMetadataKey = "request_path"

RequestPathMetadataKey stores the inbound HTTP request path (e.g. "/v1/images/generations") in Options.Metadata. It is optional and may be absent for non-HTTP executions.

View Source
const RequestedModelMetadataKey = "requested_model"

RequestedModelMetadataKey stores the client-requested model name in Options.Metadata.

View Source
const ServiceTierMetadataKey = "service_tier"

ServiceTierMetadataKey stores the client-requested service tier for usage logs.

Variables

View Source
var ErrNoActiveUpstreamWebsocket = errors.New("no active upstream websocket for response.interrupt")

ErrNoActiveUpstreamWebsocket means response.interrupt has no live upstream socket.

View Source
var ErrUpstreamWebsocketInterruptRejected = errors.New("response.interrupt does not target the active upstream response")

ErrUpstreamWebsocketInterruptRejected means a live upstream socket owns the current turn, but response.interrupt does not target its running response (unknown id, or that response already finished). Handlers must reject the frame outright and must not fall back to local cancellation, which would cancel a healthy websocket turn.

Functions

func AuthorizeWebsocketTurn added in v8.0.39

func AuthorizeWebsocketTurn(ctx context.Context, payload []byte) ([]byte, error)

func BindExecutionResource

func BindExecutionResource(opts Options, closer io.Closer) error

BindExecutionResource binds a closer to the execution lifecycle.

func DownstreamWebsocket

func DownstreamWebsocket(ctx context.Context) bool

DownstreamWebsocket reports whether the current request originates from a downstream websocket connection.

func IsConfiguredTLSHandshakeTimeoutError added in v8.0.29

func IsConfiguredTLSHandshakeTimeoutError(err error) bool

IsConfiguredTLSHandshakeTimeoutError reports whether err is exclusively explained by configured TLS handshake deadlines.

Every context.Canceled or context.DeadlineExceeded occurrence in the error tree must be contained in a ConfiguredTLSHandshakeTimeoutError subtree, and at least one configured timeout subtree must itself contain a deadline. A caller-owned cancellation or deadline anywhere outside such a subtree therefore wins, including when it is combined with a configured timeout through errors.Join. Matching error text is never sufficient on its own.

func IsUpstreamWebsocketReplayRequired

func IsUpstreamWebsocketReplayRequired(err error) bool

IsUpstreamWebsocketReplayRequired reports whether err is the internal replay signal.

func IsUpstreamWebsocketTurnError added in v8.0.45

func IsUpstreamWebsocketTurnError(err error) bool

IsUpstreamWebsocketTurnError reports whether err is a recoverable upstream websocket loss.

func LocalWebsocketTurnExecuted added in v8.0.64

func LocalWebsocketTurnExecuted(ctx context.Context) bool

LocalWebsocketTurnExecuted reports whether the current downstream websocket turn was fulfilled locally rather than on an upstream websocket.

func MarkLocalWebsocketTurn added in v8.0.64

func MarkLocalWebsocketTurn(ctx context.Context)

MarkLocalWebsocketTurn records that the current downstream websocket turn was answered locally without creating an upstream websocket response.

func MarkUpstreamAttempt

func MarkUpstreamAttempt(ctx context.Context)

MarkUpstreamAttempt records that the provider execution reached an upstream transport boundary.

func NewConfiguredTLSHandshakeTimeoutError added in v8.0.29

func NewConfiguredTLSHandshakeTimeoutError(cause error) error

NewConfiguredTLSHandshakeTimeoutError wraps the handshake failure that resulted from an internally configured TLS handshake deadline.

func NewUpstreamWebsocketReplayRequiredError

func NewUpstreamWebsocketReplayRequiredError() error

NewUpstreamWebsocketReplayRequiredError creates a request-scoped replay signal.

func NotifyWebsocketInputLoss added in v8.0.45

func NotifyWebsocketInputLoss(ctx context.Context)

NotifyWebsocketInputLoss advances the session's loss epoch if present.

func RequestProxyURL

func RequestProxyURL(ctx context.Context) string

RequestProxyURL returns the execution-scoped proxy override, or empty when unset.

func RequiredUpstreamWebsocket

func RequiredUpstreamWebsocket(ctx context.Context) bool

RequiredUpstreamWebsocket reports whether falling back to an HTTP upstream would lose request context.

func ResetLocalWebsocketTurn added in v8.0.64

func ResetLocalWebsocketTurn(ctx context.Context)

ResetLocalWebsocketTurn clears the local websocket turn marker before a new auth attempt.

func ResponseFormatOrSource

func ResponseFormatOrSource(opts Options) sdktranslator.Format

ResponseFormatOrSource returns the response target format for an execution.

func UpstreamAttempted

func UpstreamAttempted(ctx context.Context) bool

UpstreamAttempted reports whether the tracked provider execution reached an upstream transport boundary.

func WebsocketAuthEnabled

func WebsocketAuthEnabled(ctx context.Context, authID string) bool

func WebsocketInputFromContext

func WebsocketInputFromContext(ctx context.Context) <-chan WebsocketInput

func WebsocketInputLossError added in v8.0.45

func WebsocketInputLossError(ctx context.Context) error

WebsocketInputLossError returns the turn error for a downstream websocket frame whose input epoch predates the latest upstream connection loss.

func WebsocketInputPredatesLoss added in v8.0.45

func WebsocketInputPredatesLoss(ctx context.Context) bool

WebsocketInputPredatesLoss reports whether the current turn's input was read before an upstream websocket loss.

func WithDownstreamWebsocket

func WithDownstreamWebsocket(ctx context.Context) context.Context

WithDownstreamWebsocket marks the current request as coming from a downstream websocket connection.

func WithLocalWebsocketTurnTracker added in v8.0.64

func WithLocalWebsocketTurnTracker(ctx context.Context) context.Context

WithLocalWebsocketTurnTracker installs a tracker that records when a downstream websocket turn was fulfilled locally over HTTP rather than establishing or owning an upstream websocket response.

func WithRequestProxyURL

func WithRequestProxyURL(ctx context.Context, proxyURL string) context.Context

WithRequestProxyURL replaces the execution-scoped proxy override. An empty proxy clears any override inherited from the parent context.

func WithRequiredUpstreamWebsocket

func WithRequiredUpstreamWebsocket(ctx context.Context) context.Context

WithRequiredUpstreamWebsocket marks a request whose incremental context is valid only on the current upstream websocket.

func WithUpstreamAttemptTracker

func WithUpstreamAttemptTracker(ctx context.Context) context.Context

WithUpstreamAttemptTracker installs a fresh tracker for one provider execution attempt.

func WithWebsocketAuthCheck

func WithWebsocketAuthCheck(ctx context.Context, check func(string) bool) context.Context

func WithWebsocketInput

func WithWebsocketInput(ctx context.Context, input <-chan WebsocketInput) context.Context

func WithWebsocketInputEpoch added in v8.0.45

func WithWebsocketInputEpoch(ctx context.Context, epoch *atomic.Uint64, messageEpoch uint64) context.Context

WithWebsocketInputEpoch attaches the session's loss epoch counter and the current message's read epoch so executors can advance the epoch on upstream loss and reject messages that were read before an upstream loss.

func WithWebsocketTurnAuthorizer added in v8.0.39

func WithWebsocketTurnAuthorizer(ctx context.Context, authorize func([]byte) ([]byte, error)) context.Context

WithWebsocketTurnAuthorizer supplies a per-turn frontend access check for follow-up response.create and response.append frames on a duplex socket. Returning a non-empty error payload rejects the turn while keeping the socket open.

func WithoutRequestProxyURL

func WithoutRequestProxyURL(ctx context.Context) context.Context

WithoutRequestProxyURL removes an execution-scoped proxy override. Credential refresh uses this so token exchange keeps the account or global proxy.

Types

type ConfiguredTLSHandshakeTimeoutError added in v8.0.29

type ConfiguredTLSHandshakeTimeoutError struct {
	// contains filtered or unexported fields
}

ConfiguredTLSHandshakeTimeoutError identifies a TLS handshake failure caused by an internally configured establishment bound rather than by the caller's request context. Transports construct it only after they have established that the parent context was still live and their own handshake child context expired.

The concrete type is deliberately shared through this neutral executor package so both transport helpers and auth retry classification can recognize it without importing each other or trusting error text.

func (*ConfiguredTLSHandshakeTimeoutError) Error added in v8.0.29

func (*ConfiguredTLSHandshakeTimeoutError) Unwrap added in v8.0.29

Unwrap preserves the original handshake error chain, including context.DeadlineExceeded, for diagnostics and errors.Is checks.

type ExecutionLifecycle

type ExecutionLifecycle interface {
	Bind(func() error) error
	End(string)
}

ExecutionLifecycle owns resources associated with an execution attempt.

type Options

type Options struct {
	// Stream toggles streaming mode.
	Stream bool
	// Alt carries optional alternate format hint (e.g. SSE JSON key).
	Alt string
	// Headers are forwarded to the provider request builder.
	Headers http.Header
	// Query contains optional query string parameters.
	Query url.Values
	// OriginalRequest preserves the inbound request bytes prior to translation.
	OriginalRequest []byte
	// SourceFormat identifies the inbound schema.
	SourceFormat sdktranslator.Format
	// ResponseFormat identifies the downstream response schema.
	// Empty means responses should use SourceFormat for backward compatibility.
	ResponseFormat sdktranslator.Format
	// Metadata carries extra execution hints shared across selection and executors.
	Metadata map[string]any
	// RequestBeforeAuthInterceptor runs before after-auth interception on bound follow-up turns.
	RequestBeforeAuthInterceptor RequestBeforeAuthInterceptor
	// RequestAfterAuthInterceptor runs after credential selection and before executor translation.
	RequestAfterAuthInterceptor RequestAfterAuthInterceptor
	// WebSocketResponseObserver receives upstream WebSocket response events during execution.
	WebSocketResponseObserver WebSocketResponseObserver
	// ExecutionLifecycle owns Home-dispatched execution resources. Executors must not add it to request metadata.
	ExecutionLifecycle ExecutionLifecycle
	// ProxyURL overrides the credential and global proxy for this execution only.
	// Credential refresh and token exchange must ignore it.
	ProxyURL string
	// KeepTopLevelEffort tells SIWC request-body rules to keep the resolved
	// top-level reasoning.effort when configuration_update items are collapsed.
	KeepTopLevelEffort bool
}

Options controls execution behavior for both streaming and non-streaming calls.

func (*Options) EnsureMetadata

func (o *Options) EnsureMetadata() map[string]any

EnsureMetadata initializes and returns Metadata, ensuring it is non-nil.

type Request

type Request struct {
	// Model is the upstream model identifier after translation.
	Model string
	// Payload is the provider specific JSON payload.
	Payload []byte
	// Format represents the provider payload schema.
	Format sdktranslator.Format
	// Metadata carries optional provider specific execution hints.
	Metadata map[string]any
}

Request encapsulates the translated payload that will be sent to a provider executor.

type RequestAfterAuthInterceptRequest

type RequestAfterAuthInterceptRequest struct {
	// SourceFormat is the original client protocol format.
	SourceFormat sdktranslator.Format
	// ToFormat is the selected upstream protocol format.
	ToFormat sdktranslator.Format
	// Model is the selected upstream model for this attempt.
	Model string
	// RequestedModel is the client-requested model before alias/model-pool rewriting.
	RequestedModel string
	// Stream reports whether the request expects streaming output.
	Stream bool
	// Headers contains the current upstream request headers.
	Headers http.Header
	// Body contains the current request payload. Treat it as read-only; modifications must be returned in RequestAfterAuthInterceptResponse.Body.
	Body []byte
	// Metadata is a best-effort cloned context snapshot. Treat it as read-only and JSON-like.
	Metadata map[string]any
}

RequestAfterAuthInterceptRequest describes a selected-auth request before executor translation.

type RequestAfterAuthInterceptResponse

type RequestAfterAuthInterceptResponse struct {
	// Path optionally overrides the inbound request path in Options.Metadata[RequestPathMetadataKey].
	Path string
	// Headers replaces matching current request headers and preserves headers not mentioned here.
	Headers http.Header
	// Body replaces the current request body only when non-empty.
	Body []byte
	// ClearHeaders explicitly removes current request headers before Headers is applied.
	ClearHeaders []string
	// Terminate prevents the selected executor from receiving the request.
	Terminate bool
	// StatusCode is the downstream HTTP status used when Terminate is true.
	StatusCode int
	// ResponseHeaders contains downstream response headers used when Terminate is true.
	ResponseHeaders http.Header
	// ResponseBody contains the downstream response body used when Terminate is true.
	ResponseBody []byte
}

RequestAfterAuthInterceptResponse returns selected-auth request modifications.

type RequestAfterAuthInterceptor

RequestAfterAuthInterceptor rewrites a request after credential selection and before executor translation.

type RequestBeforeAuthInterceptor added in v8.0.47

RequestBeforeAuthInterceptor rewrites a follow-up request on a bound session before after-auth interception.

type RequestScopedError

type RequestScopedError interface {
	error
	IsRequestScoped() bool
}

RequestScopedError identifies a failure tied to the current request rather than the selected credential. Auth managers should not retry these errors across credentials or change credential availability because of them.

type RequestTerminatedError

type RequestTerminatedError struct {
	HTTPStatus int
	Header     http.Header
	Body       []byte
}

RequestTerminatedError carries a plugin-defined downstream response without executing upstream.

func (*RequestTerminatedError) Error

func (e *RequestTerminatedError) Error() string

func (*RequestTerminatedError) ResponseBody

func (e *RequestTerminatedError) ResponseBody() []byte

ResponseBody returns a copy of the plugin-defined downstream body.

func (*RequestTerminatedError) ResponseHeaders

func (e *RequestTerminatedError) ResponseHeaders() http.Header

ResponseHeaders returns a copy of the plugin-defined downstream headers.

func (*RequestTerminatedError) StatusCode

func (e *RequestTerminatedError) StatusCode() int

StatusCode returns the plugin-defined downstream HTTP status.

type Response

type Response struct {
	// Payload is the provider response in the executor format.
	Payload []byte
	// Incomplete reports that the upstream execution terminated in an incomplete state
	// (e.g., response.incomplete) even if translated into a normal non-stream payload.
	Incomplete bool
	// Metadata exposes optional structured data for translators.
	Metadata map[string]any
	// Headers carries upstream HTTP response headers for passthrough to clients.
	Headers http.Header
}

Response wraps either a full provider response or metadata for streaming flows.

type StatusError

type StatusError interface {
	error
	StatusCode() int
}

StatusError represents an error that carries an HTTP-like status code. Provider executors should implement this when possible to enable better auth state updates on failures (e.g., 401/402/429).

type StreamChunk

type StreamChunk struct {
	// Payload is the raw provider chunk payload.
	Payload []byte
	// Incomplete reports that the upstream stream ended in an incomplete terminal state
	// (e.g., response.incomplete) even if protocol translation mapped it to a normal chunk.
	Incomplete bool
	// Err reports any terminal error encountered while producing chunks.
	Err error
}

StreamChunk represents a single streaming payload unit emitted by provider executors.

type StreamResult

type StreamResult struct {
	// Headers carries upstream HTTP response headers from the initial connection.
	Headers http.Header
	// Chunks is the channel of streaming payload units.
	Chunks <-chan StreamChunk
}

StreamResult wraps the streaming response, providing both the chunk channel and the upstream HTTP response headers captured before streaming begins.

type StreamTruncatedError added in v8.0.44

type StreamTruncatedError interface {
	error
	IsStreamTruncated() bool
}

StreamTruncatedError identifies a locally synthesized failure for an accepted upstream stream that ended without its terminal frame. The upstream generation was already submitted, so auth managers must not cool the credential or replay the request on another credential because of it.

type TransientRateLimitError added in v8.0.45

type TransientRateLimitError interface {
	error
	IsTransientRateLimit() bool
}

TransientRateLimitError identifies a transient per-model capacity or admission rejection (for example a Codex turn_rate_limit_exceeded 429). The credential's plan quota is not exhausted, so auth managers must not record quota exhaustion or advance the quota exponential backoff for it. The rejecting model may still cool until any provider RetryAfter hint.

type UpstreamWebsocketReplayRequiredError

type UpstreamWebsocketReplayRequiredError struct{}

UpstreamWebsocketReplayRequiredError indicates that an incremental request cannot safely continue because its upstream websocket is no longer reusable.

func (*UpstreamWebsocketReplayRequiredError) Error

func (*UpstreamWebsocketReplayRequiredError) IsRequestScoped

func (*UpstreamWebsocketReplayRequiredError) IsRequestScoped() bool

func (*UpstreamWebsocketReplayRequiredError) StatusCode

type UpstreamWebsocketTurnError added in v8.0.45

type UpstreamWebsocketTurnError struct {
	Cause error
	// FullContextRequired marks a continuation (previous_response_id, append) that refers to
	// the lost socket: nothing was sent, the client resends the full input.
	FullContextRequired bool
	// NotSent marks an operation that was never written upstream.
	NotSent bool
	EventID string
	// Idle marks a loss with no running turn: only Abandoned is reported, if anything.
	Idle bool
	// Abandoned lists the other operations that lose their outcome with this turn.
	Abandoned []*UpstreamWebsocketTurnError
}

UpstreamWebsocketTurnError ends one downstream websocket turn after the upstream websocket was lost. The downstream socket stays open and the turn is never replayed. Cause is kept for logging and is never sent to the client.

func (*UpstreamWebsocketTurnError) Error added in v8.0.45

func (*UpstreamWebsocketTurnError) IsRequestScoped added in v8.0.45

func (*UpstreamWebsocketTurnError) IsRequestScoped() bool

func (*UpstreamWebsocketTurnError) StatusCode added in v8.0.45

func (e *UpstreamWebsocketTurnError) StatusCode() int

func (*UpstreamWebsocketTurnError) Unwrap added in v8.0.45

func (e *UpstreamWebsocketTurnError) Unwrap() error

type WebSocketResponseEvent

type WebSocketResponseEvent struct {
	RequestID      string
	TraceID        string
	SourceFormat   string
	Model          string
	RequestedModel string
	Provider       string
	AuthID         string
	AuthLabel      string
	AuthType       string
	EventType      string
	Payload        []byte
	Metadata       map[string]any
}

WebSocketResponseEvent describes an upstream WebSocket response event received during execution.

type WebSocketResponseObserver

type WebSocketResponseObserver func(context.Context, WebSocketResponseEvent)

WebSocketResponseObserver receives upstream WebSocket response events during execution.

type WebsocketInput

type WebsocketInput struct {
	Payload []byte
	Err     error
	// Epoch is the downstream input epoch at read time; a loss advances it.
	Epoch uint64
}

WebsocketInput is a frame from the single downstream reader. Err terminates the connection; Payload is owned by the receiver and must not be replayed.

Jump to

Keyboard shortcuts

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