Documentation
¶
Index ¶
- Constants
- Variables
- func IsTransientLiveEvent(eventType string) bool
- func OpenNATSEventBridgeFromEnv(sink EventSink) (bool, func(), error)
- type AppCallbackEventSink
- type AppCallbackRoute
- type CallbackEventSink
- type CallbackEventSinkConfig
- type Config
- type DurableExecutionDescriber
- type DurableExecutionInspector
- type DurableExecutor
- type Engine
- func (e *Engine) CancelRun(ctx context.Context, appID, runID string) (*agentcore.AgentRun, error)
- func (e *Engine) CleanupTerminalWorkspace(ctx context.Context, appID, runID string) error
- func (e *Engine) ExecuteRunOnce(ctx context.Context, appID, runID string) (*runtime.Result, error)
- func (e *Engine) ExecutesCommandCapableRuns() bool
- func (e *Engine) GetRunExecution(ctx context.Context, appID, runID string) (*RunExecutionInfo, error)
- func (e *Engine) MarkRunManuallyPaused(ctx context.Context, appID, runID string) (bool, error)
- func (e *Engine) PauseRun(ctx context.Context, appID, runID string) (*agentcore.AgentRun, error)
- func (e *Engine) PrepareRunOnce(ctx context.Context, appID, runID string) error
- func (e *Engine) ReconcileDurableRuns(ctx context.Context, olderThan time.Time) (int, error)
- func (e *Engine) RecoverInterruptedLightweightRuns(ctx context.Context) (int, error)
- func (e *Engine) ResumeRun(ctx context.Context, appID, runID string, payload ResumePayload) (*agentcore.AgentRun, error)
- func (e *Engine) RevokeRunModelCredential(ctx context.Context, appID, runID string) error
- func (e *Engine) RunToolGateway(ctx context.Context, appID, runID string) (*mcp.Gateway, func(), error)
- func (e *Engine) StartRun(ctx context.Context, req StartRunRequest) (*agentcore.AgentRun, error)
- func (e *Engine) UpdateRunMCPCredential(ctx context.Context, appID, runID, serverID string, ...) (*RunMCPCredentialUpdate, error)
- func (e *Engine) UpdateRunModelCredential(ctx context.Context, appID, runID string, c sdk.ModelCredential) (*sdk.RunModelCredentialUpdate, error)
- type Event
- type EventBroker
- type EventSink
- type MultiEventSink
- type NATSEventSink
- type NATSEventSinkConfig
- type NATSRuntimeEvent
- type NoopEventSink
- type PersistedEventSink
- type ResumePayload
- type RunExecutionInfo
- type RunMCPCredentialUpdate
- type SlogEventSink
- type StartRunRequest
- type V2EventEnvelope
- type V2EventPublisher
Constants ¶
const ( ExecutionModeDurable = "durable" ExecutionModeLightweight = "lightweight" )
const ( DurableExecutionRunning = "running" DurableExecutionCompleted = "completed" DurableExecutionFailed = "failed" DurableExecutionCancelled = "cancelled" DurableExecutionMissing = "missing" )
const CodingMetadataKey = "native_coding"
CodingMetadataKey is persisted only after admission resolves effective tools.
const (
EventSchemaVersionV2 = "2"
)
Variables ¶
ErrCodingUnavailable prevents coding work from entering the default shared queues.
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.
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 OpenNATSEventBridgeFromEnv ¶
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
type AppCallbackRoute ¶
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
type CallbackEventSinkConfig ¶
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 DurableExecutor ¶
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
func (*Engine) CleanupTerminalWorkspace ¶ added in v0.11.2
CleanupTerminalWorkspace executes on the run's original worker queue so paused cancellations also reach the retained execution volume.
func (*Engine) ExecuteRunOnce ¶
func (*Engine) ExecutesCommandCapableRuns ¶ added in v0.11.2
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 (*Engine) MarkRunManuallyPaused ¶ added in v0.13.2
MarkRunManuallyPaused records a pause after the workflow has stopped its active activity. A terminal or independently paused run is left untouched.
func (*Engine) PauseRun ¶ added in v0.13.2
PauseRun requests a manual pause without terminalizing the run. The worker emits run.paused after the current execution activity has stopped.
func (*Engine) PrepareRunOnce ¶
func (*Engine) ReconcileDurableRuns ¶
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) RecoverInterruptedLightweightRuns ¶ added in v0.13.8
RecoverInterruptedLightweightRuns re-executes lightweight runs that were queued or running when the previous runtime process stopped. Lightweight runs execute inside the runtime process, so after a restart nothing else can be executing them; native checkpoint recovery continues each run without replaying completed tools. Callers must only use this when a single runtime process owns the store, which is why it is opt-in.
func (*Engine) RevokeRunModelCredential ¶
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) 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 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 ¶
func OpenEventSinkFromEnv ¶
type MultiEventSink ¶
type MultiEventSink []EventSink
type NATSEventSink ¶
type NATSEventSink struct {
// contains filtered or unexported fields
}
func NewNATSEventSink ¶
func NewNATSEventSink(publisher natsEventPublisher, subjectTemplate string) *NATSEventSink
type NATSEventSinkConfig ¶
type NATSRuntimeEvent ¶
type NATSRuntimeEvent = sdk.EventEnvelope
type NoopEventSink ¶
type NoopEventSink struct{}
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.
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{}
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.