executor

package
v7.3.12 Latest Latest
Warning

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

Go to latest
Published: Sep 22, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// PinnedAuthMetadataKey locks execution to a specific auth ID.
	PinnedAuthMetadataKey = "pinned_auth_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"
	// 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

This section is empty.

Functions

func BindExecutionResource added in v7.2.96

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 IsUpstreamWebsocketReplayRequired added in v7.2.97

func IsUpstreamWebsocketReplayRequired(err error) bool

IsUpstreamWebsocketReplayRequired reports whether err is the internal replay signal.

func MarkUpstreamAttempt added in v7.2.146

func MarkUpstreamAttempt(ctx context.Context)

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

func NewUpstreamWebsocketReplayRequiredError added in v7.2.97

func NewUpstreamWebsocketReplayRequiredError() error

NewUpstreamWebsocketReplayRequiredError creates a request-scoped replay signal.

func RequestProxyURL added in v7.3.12

func RequestProxyURL(ctx context.Context) string

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

func RequiredUpstreamWebsocket added in v7.2.97

func RequiredUpstreamWebsocket(ctx context.Context) bool

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

func ResponseFormatOrSource added in v7.1.67

func ResponseFormatOrSource(opts Options) sdktranslator.Format

ResponseFormatOrSource returns the response target format for an execution.

func UpstreamAttempted added in v7.2.146

func UpstreamAttempted(ctx context.Context) bool

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

func WebsocketAuthEnabled added in v7.3.9

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

func WebsocketInputFromContext added in v7.3.9

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

func WithDownstreamWebsocket

func WithDownstreamWebsocket(ctx context.Context) context.Context

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

func WithRequestProxyURL added in v7.3.12

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 added in v7.2.97

func WithRequiredUpstreamWebsocket(ctx context.Context) context.Context

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

func WithUpstreamAttemptTracker added in v7.2.146

func WithUpstreamAttemptTracker(ctx context.Context) context.Context

WithUpstreamAttemptTracker installs a fresh tracker for one provider execution attempt.

func WithWebsocketAuthCheck added in v7.3.9

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

func WithWebsocketInput added in v7.3.9

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

func WithoutRequestProxyURL added in v7.3.12

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 ExecutionLifecycle added in v7.2.96

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
	// 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
}

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

func (*Options) EnsureMetadata added in v7.2.133

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 added in v7.1.62

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.
	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 added in v7.1.62

type RequestAfterAuthInterceptResponse struct {
	// 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 added in v7.1.62

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

type RequestScopedError added in v7.2.80

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 added in v7.2.103

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

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

func (*RequestTerminatedError) Error added in v7.2.103

func (e *RequestTerminatedError) Error() string

func (*RequestTerminatedError) ResponseBody added in v7.2.103

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

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

func (*RequestTerminatedError) ResponseHeaders added in v7.2.103

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

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

func (*RequestTerminatedError) StatusCode added in v7.2.103

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
	// 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
	// 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 UpstreamWebsocketReplayRequiredError added in v7.2.97

type UpstreamWebsocketReplayRequiredError struct{}

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

func (*UpstreamWebsocketReplayRequiredError) Error added in v7.2.97

func (*UpstreamWebsocketReplayRequiredError) IsRequestScoped added in v7.2.97

func (*UpstreamWebsocketReplayRequiredError) IsRequestScoped() bool

func (*UpstreamWebsocketReplayRequiredError) StatusCode added in v7.2.97

type WebSocketResponseEvent added in v7.2.143

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 added in v7.2.143

type WebSocketResponseObserver func(context.Context, WebSocketResponseEvent)

WebSocketResponseObserver receives upstream WebSocket response events during execution.

type WebsocketInput added in v7.3.9

type WebsocketInput struct {
	Payload []byte
	Err     error
}

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