Help us shape the future of Go! Take the 2026 Go Developer Survey

engine

package
v0.13.1 Latest Latest
Warning

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

Go to latest
Published: Sep 24, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ExecutionModeDurable     = "durable"
	ExecutionModeLightweight = "lightweight"
)
View Source
const (
	DurableExecutionRunning   = "running"
	DurableExecutionCompleted = "completed"
	DurableExecutionFailed    = "failed"
	DurableExecutionCancelled = "cancelled"
	DurableExecutionMissing   = "missing"
)
View Source
const CodingMetadataKey = "native_coding"

CodingMetadataKey is persisted only after admission resolves effective tools.

View Source
const (
	EventSchemaVersionV2 = "2"
)

Variables

View Source
var ErrCodingUnavailable = errors.New("This tool policy requires an isolated coding worker. Configure a coding worker or remove shell and workspace-write tools before starting a new run.")

ErrCodingUnavailable prevents coding work from entering the default shared queues.

View Source
var ErrRetiredRuntime = errors.New("This run used a retired coding engine and cannot continue. Start a new run using native_sdk; review existing changes and completed actions before retrying.")

ErrRetiredRuntime is also used for historical runs whose executor is gone.

View Source
var ErrRunModelCredentialsRequired = errors.New("This app requires an explicit run model and model credential. Configure an AI connection in the host app before starting the run.")

ErrRunModelCredentialsRequired rejects ambient credentials for opted-in apps.

Functions

func IsTransientLiveEvent

func IsTransientLiveEvent(eventType string) bool

func OpenNATSEventBridgeFromEnv

func OpenNATSEventBridgeFromEnv(sink EventSink) (bool, func(), error)

OpenNATSEventBridgeFromEnv forwards the shared worker event subject into an API-local broker. It is intentionally live-only; durable history is supplied by PersistedEventSink.

Types

type AppCallbackEventSink

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

AppCallbackEventSink routes events only to callbacks configured for the event's app_id. It deliberately remains separate from the global event sink selected by AGENT_RUNTIME_EVENT_SINK so log/NATS topology stays shared while HTTP delivery and credentials remain app-scoped.

func NewAppCallbackEventSink

func NewAppCallbackEventSink(routes []AppCallbackRoute, client *http.Client) *AppCallbackEventSink

func (*AppCallbackEventSink) Emit

func (s *AppCallbackEventSink) Emit(ctx context.Context, event Event)

type AppCallbackRoute

type AppCallbackRoute struct {
	AppID      string
	URL        string
	Token      string
	EventTypes []string
}

AppCallbackRoute scopes one HTTP callback to a single host application. An empty EventTypes list accepts every event emitted for the app.

type CallbackEventSink

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

func NewCallbackEventSink

func NewCallbackEventSink(url, token string, client *http.Client) *CallbackEventSink

func (*CallbackEventSink) Emit

func (s *CallbackEventSink) Emit(ctx context.Context, event Event)

type CallbackEventSinkConfig

type CallbackEventSinkConfig struct {
	URL     string
	Token   string
	Timeout time.Duration
}

type Config

type Config struct {
	// ManualLightweightExecution lets an embedded caller own execution and cancellation.
	// The caller must invoke ExecuteRunOnce after StartRun or ResumeRun.
	ManualLightweightExecution bool

	// RequireRunModelCredentials is trusted deployment policy, never run input.
	RequireRunModelCredentials func(appID string) bool
	ValidateRunModelEndpoint   func(appID string, model *sdk.RunModel) error
	ModelCredentials           *modelauth.Manager
	DefaultExecutionMode       string
	Store                      agentcore.Store
	Runtimes                   *runtime.Registry
	Tools                      *tools.Registry
	Targets                    host.TargetContextProvider
	Skills                     *skills.Registry
	SkillPackages              *skills.PackageStoreRegistry
	Workspaces                 *workspace.Registry
	Durable                    DurableExecutor
	EventSink                  EventSink
	RunMCP                     mcp.RunConfig
	CodingWorker               bool
	CheckCodingAdmission       func(context.Context) error
}

type DurableExecutionDescriber

type DurableExecutionDescriber interface {
	DescribeRun(ctx context.Context, run *agentcore.AgentRun) (*RunExecutionInfo, error)
}

type DurableExecutionInspector

type DurableExecutionInspector interface {
	InspectRun(ctx context.Context, run *agentcore.AgentRun) (string, error)
}

type DurableExecutor

type DurableExecutor interface {
	StartRun(ctx context.Context, run *agentcore.AgentRun) error
	CancelRun(ctx context.Context, run *agentcore.AgentRun) error
	ResumeRun(ctx context.Context, run *agentcore.AgentRun, payload ResumePayload) error
}

type Engine

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

func New

func New(cfg Config) *Engine

func (*Engine) CancelRun

func (e *Engine) CancelRun(ctx context.Context, appID, runID string) (*agentcore.AgentRun, error)

func (*Engine) CleanupTerminalWorkspace added in v0.11.2

func (e *Engine) CleanupTerminalWorkspace(ctx context.Context, appID, runID string) error

CleanupTerminalWorkspace executes on the run's original worker queue so paused cancellations also reach the retained execution volume.

func (*Engine) ExecuteRunOnce

func (e *Engine) ExecuteRunOnce(ctx context.Context, appID, runID string) (*runtime.Result, error)

func (*Engine) ExecutesCommandCapableRuns added in v0.11.2

func (e *Engine) ExecutesCommandCapableRuns() bool

ExecutesCommandCapableRuns reports whether this engine runs in an execution role, that is one that owns a writable workspace volume and serves the command-capable queues. Such roles fence each run's workspace with a lock before touching it.

func (*Engine) GetRunExecution

func (e *Engine) GetRunExecution(ctx context.Context, appID, runID string) (*RunExecutionInfo, error)

func (*Engine) PrepareRunOnce

func (e *Engine) PrepareRunOnce(ctx context.Context, appID, runID string) error

func (*Engine) ReconcileDurableRuns

func (e *Engine) ReconcileDurableRuns(ctx context.Context, olderThan time.Time) (int, error)

ReconcileDurableRuns repairs the narrow failure window where a run row was committed but its Temporal workflow was not started. When the durable executor supports inspection, it also terminates stale active database rows whose Temporal workflow is missing or already closed.

func (*Engine) ResumeRun

func (e *Engine) ResumeRun(ctx context.Context, appID, runID string, payload ResumePayload) (*agentcore.AgentRun, error)

func (*Engine) RevokeRunModelCredential

func (e *Engine) RevokeRunModelCredential(ctx context.Context, appID, runID string) error

func (*Engine) RunToolGateway

func (e *Engine) RunToolGateway(ctx context.Context, appID, runID string) (*mcp.Gateway, func(), error)

RunToolGateway prepares the same isolated registry and allowlist used by an adapter execution. Callers must invoke the returned close function.

func (*Engine) StartRun

func (e *Engine) StartRun(ctx context.Context, req StartRunRequest) (*agentcore.AgentRun, error)

func (*Engine) UpdateRunMCPCredential

func (e *Engine) UpdateRunMCPCredential(
	ctx context.Context,
	appID, runID, serverID string,
	credential mcp.RunCredential,
) (*RunMCPCredentialUpdate, error)

UpdateRunMCPCredential replaces only the encrypted credential for an existing run attachment. Server identity, URL, transport, and tool policy remain immutable for the lifetime of the run.

func (*Engine) UpdateRunModelCredential

func (e *Engine) UpdateRunModelCredential(ctx context.Context, appID, runID string, c sdk.ModelCredential) (*sdk.RunModelCredentialUpdate, error)

type Event

type Event = sdk.Event

type EventBroker

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

EventBroker is an in-process fan-out EventSink. It receives every emitted Event (engine lifecycle events plus the runtime adapters' token-level assistant_message_* / tool_call_* events) and delivers them to per-run subscribers, so an SSE endpoint can stream a run live.

Sends are non-blocking: if a subscriber's buffer is full (a slow client) the event is dropped for that subscriber rather than stalling the engine. The client reconciles against the persisted run via a refetch.

func NewEventBroker

func NewEventBroker() *EventBroker

func (*EventBroker) Emit

func (b *EventBroker) Emit(_ context.Context, event Event)

Emit fans an event out to every subscriber of event.RunID.

func (*EventBroker) Subscribe

func (b *EventBroker) Subscribe(runID string) (<-chan Event, func())

Subscribe returns a channel of events for a run and an unsubscribe function the caller must invoke when done.

type EventSink

type EventSink interface {
	Emit(ctx context.Context, event Event)
}

func OpenEventSinkFromEnv

func OpenEventSinkFromEnv() (EventSink, func(), error)

type MultiEventSink

type MultiEventSink []EventSink

func (MultiEventSink) Emit

func (s MultiEventSink) Emit(ctx context.Context, event Event)

type NATSEventSink

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

func NewNATSEventSink

func NewNATSEventSink(publisher natsEventPublisher, subjectTemplate string) *NATSEventSink

func (*NATSEventSink) Emit

func (s *NATSEventSink) Emit(_ context.Context, event Event)

type NATSEventSinkConfig

type NATSEventSinkConfig struct {
	URL             string
	ClientName      string
	StreamName      string
	StreamSubjects  []string
	SubjectTemplate string
	EnsureStream    bool
}

type NATSRuntimeEvent

type NATSRuntimeEvent = sdk.EventEnvelope

type NoopEventSink

type NoopEventSink struct{}

func (NoopEventSink) Emit

type PersistedEventSink

type PersistedEventSink struct {
	Store       agentcore.Store
	V2Enabled   func(appID string) bool
	V2Publisher V2EventPublisher
}

PersistedEventSink writes the host-neutral event envelope to the shared run store. API and Temporal worker processes both install it, allowing run history and SSE replay across process boundaries.

func (PersistedEventSink) Emit

func (s PersistedEventSink) Emit(ctx context.Context, event Event)

type ResumePayload

type ResumePayload struct {
	MessageProvenance string                `json:"message_provenance,omitempty"`
	Intent            string                `json:"intent"`
	Content           string                `json:"content,omitempty"`
	ResponsePayload   json.RawMessage       `json:"response_payload,omitempty"`
	ExternalActorID   string                `json:"external_actor_id,omitempty"`
	ResumeID          string                `json:"resume_id,omitempty"`
	InteractionID     string                `json:"interaction_id,omitempty"`
	TurnPolicy        *agentcore.TurnPolicy `json:"turn_policy,omitempty"`
}

ResumePayload extends the public SDK request with optional correlation fields. Older clients can omit both fields; newer hosts should send a stable resume_id for retries and the interaction_id they are resolving.

type RunExecutionInfo

type RunExecutionInfo struct {
	ExecutionMode        string     `json:"execution_mode"`
	State                string     `json:"state"`
	WorkflowID           string     `json:"workflow_id,omitempty"`
	TemporalRunID        string     `json:"temporal_run_id,omitempty"`
	TaskQueue            string     `json:"task_queue,omitempty"`
	HistoryLength        int64      `json:"history_length,omitempty"`
	HistorySizeBytes     int64      `json:"history_size_bytes,omitempty"`
	StateTransitionCount int64      `json:"state_transition_count,omitempty"`
	StartedAt            *time.Time `json:"started_at,omitempty"`
	ClosedAt             *time.Time `json:"closed_at,omitempty"`
}

type RunMCPCredentialUpdate

type RunMCPCredentialUpdate struct {
	RunID     string     `json:"run_id"`
	ServerID  string     `json:"server_id"`
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
	UpdatedAt time.Time  `json:"updated_at"`
}

RunMCPCredentialUpdate is the non-secret acknowledgement returned after a host app rotates one existing run-scoped MCP credential.

type SlogEventSink

type SlogEventSink struct{}

func (SlogEventSink) Emit

func (SlogEventSink) Emit(_ context.Context, event Event)

type StartRunRequest

type StartRunRequest struct {
	Model           *sdk.RunModel          `json:"model,omitempty"`
	ModelCredential *sdk.ModelCredential   `json:"model_credential,omitempty"`
	AppID           string                 `json:"app_id"`
	HostRunID       string                 `json:"host_run_id,omitempty"`
	AgentID         string                 `json:"agent_id"`
	Target          agentcore.TargetRef    `json:"target"`
	Instructions    string                 `json:"instructions,omitempty"`
	AllowedTools    []string               `json:"allowed_tools,omitempty"`
	ExternalActorID string                 `json:"external_actor_id,omitempty"`
	Mode            string                 `json:"mode,omitempty"`
	ExecutionMode   string                 `json:"execution_mode,omitempty"`
	Trigger         map[string]interface{} `json:"trigger,omitempty"`
	Metadata        map[string]interface{} `json:"metadata,omitempty"`
	TurnPolicy      agentcore.TurnPolicy   `json:"turn_policy,omitempty"`
	MCPServers      []mcp.RunServerRequest `json:"mcp_servers,omitempty"`
}

type V2EventEnvelope

type V2EventEnvelope struct {
	EventID       string                 `json:"event_id"`
	SentAt        time.Time              `json:"sent_at"`
	SequenceNo    int64                  `json:"sequence_no"`
	AppID         string                 `json:"app_id"`
	RunID         string                 `json:"run_id"`
	HostRunID     string                 `json:"host_run_id,omitempty"`
	SchemaVersion string                 `json:"schema_version"`
	TurnID        string                 `json:"turn_id,omitempty"`
	SegmentID     string                 `json:"segment_id,omitempty"`
	Revision      int64                  `json:"revision"`
	BaseRevision  int64                  `json:"base_revision,omitempty"`
	Type          string                 `json:"type"`
	Data          map[string]interface{} `json:"data,omitempty"`
}

V2EventEnvelope is the stable ordered wire contract consumed by v2 hosts.

func V2EnvelopeFromPersisted

func V2EnvelopeFromPersisted(event agentcore.AgentRunEvent) V2EventEnvelope

V2EnvelopeFromPersisted maps the canonical durable row to the v2 wire shape.

type V2EventPublisher

type V2EventPublisher interface {
	PublishV2(ctx context.Context, event agentcore.AgentRunEvent) error
}

V2EventPublisher publishes a persisted event without changing its identity.

func OpenV2EventPublisherFromEnv

func OpenV2EventPublisherFromEnv() (V2EventPublisher, func(), error)

OpenV2EventPublisherFromEnv opens the versioned publisher when the shared event sink includes NATS. V1 publication remains independently configured.

Jump to

Keyboard shortcuts

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