temporal

package
v0.0.0-...-c4ca558 Latest Latest
Warning

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

Go to latest
Published: Jul 8, 2026 License: MIT Imports: 48 Imported by: 0

Documentation

Index

Constants

View Source
const (
	COMPLETED = "completed"
	SUCCEEDED = "succeeded"
)
View Source
const (
	PlanWorkflowName                  = "AgentOSPlanWorkflow"
	PlanStatusQueryName               = "agentos.plan.status"
	PlanSignalName                    = "agentos.plan.signal"
	PlanControlSignalName             = "agentos.plan.control"
	ValidatePlanActivityName          = "AgentOSValidatePlan"
	ResolvePlanNodeInputActivityName  = "AgentOSResolvePlanNodeInput"
	StartPlanNodeActivityName         = "AgentOSStartPlanNode"
	StatusPlanNodeActivityName        = "AgentOSStatusPlanNode"
	ControlPlanNodeActivityName       = "AgentOSControlPlanNode"
	PublishPlanArtifactsActivityName  = "AgentOSPublishPlanArtifacts"
	EvaluatePlanExpansionActivityName = "AgentOSEvaluatePlanExpansion"
	PersistPlanStateActivityName      = "AgentOSPersistPlanState"
)
View Source
const (
	FAILED   = "failed"
	CANCELED = "canceled"
)
View Source
const (
	ProcessWorkflowName          = "AgentOSProcessWorkflow"
	ProcessStatusQueryName       = "agentos.process.status"
	ProcessSignalName            = "agentos.process.signal"
	ProcessControlSignalName     = "agentos.process.control"
	StartProcessActivityName     = "AgentOSStartProcess"
	SignalProcessActivityName    = "AgentOSSignalProcess"
	ControlProcessActivityName   = "AgentOSControlProcess"
	FireProcessTimerActivityName = "AgentOSFireProcessTimer"
)

Variables

View Source
var (
	ErrPlanRuntimePostgresURLRequired              = errors.New("agentos temporal plan runtime: postgres url is required")
	ErrPlanRuntimeArtifactStoreBackendRequired     = errors.New("agentos temporal plan runtime: artifact store backend is required")
	ErrPlanRuntimeArtifactStoreBackendUnknown      = errors.New("agentos temporal plan runtime: artifact store backend is unknown")
	ErrPlanRuntimeArtifactStoreLocalRootRequired   = errors.New("agentos temporal plan runtime: artifact local root is required")
	ErrPlanRuntimeArtifactStoreS3BucketRequired    = errors.New("agentos temporal plan runtime: artifact s3 bucket is required")
	ErrPlanRuntimeArtifactStoreS3RegionRequired    = errors.New("agentos temporal plan runtime: artifact s3 region is required")
	ErrPlanRuntimeArtifactStoreS3AccessKeyRequired = errors.New("agentos temporal plan runtime: artifact s3 access key id is required")
	ErrPlanRuntimeArtifactStoreS3SecretKeyRequired = errors.New("agentos temporal plan runtime: artifact s3 secret access key is required")
)
View Source
var (
	ErrWorkerConfigRequired                   = errors.New("agentos temporal worker: config is required")
	ErrWorkerPostgresURLRequired              = errors.New("agentos temporal worker: postgres url is required")
	ErrWorkerRedisURLRequired                 = errors.New("agentos temporal worker: redis url is required")
	ErrWorkerArtifactStoreBackendRequired     = errors.New("agentos temporal worker: artifact store backend is required")
	ErrWorkerArtifactStoreBackendUnknown      = errors.New("agentos temporal worker: artifact store backend is unknown")
	ErrWorkerArtifactStoreLocalRootRequired   = errors.New("agentos temporal worker: artifact local root is required")
	ErrWorkerArtifactStoreS3BucketRequired    = errors.New("agentos temporal worker: artifact s3 bucket is required")
	ErrWorkerArtifactStoreS3RegionRequired    = errors.New("agentos temporal worker: artifact s3 region is required")
	ErrWorkerArtifactStoreS3AccessKeyRequired = errors.New("agentos temporal worker: artifact s3 access key id is required")
	ErrWorkerArtifactStoreS3SecretKeyRequired = errors.New("agentos temporal worker: artifact s3 secret access key is required")
)
View Source
var (
	ErrRuntimePostgresURLRequired = errors.New("agentos temporal runtime: postgres url is required")
)
View Source
var ErrTemporalTaskQueuesInvalid = errors.New("agentos temporal task queues: invalid")

Functions

func CapabilitiesWithDefaults

func CapabilitiesWithDefaults(configured []agentos.Capability) []agentos.Capability

CapabilitiesWithDefaults prepends this implementation's built-in capabilities to host-configured backend declarations.

func DefaultCapabilities

func DefaultCapabilities() []agentos.Capability

DefaultCapabilities returns capability declarations owned by this default Temporal-backed AgentOS implementation.

func NativeRunCapability

func NativeRunCapability() agentos.Capability

NativeRunCapability declares the built-in GoAgent native child-run backend.

func NewPlanRuntime

func NewPlanRuntime(ctx context.Context, cfg *RuntimeConfig) (agentos.PlanRuntime, error)

NewPlanRuntime creates the default Temporal implementation of agentos.PlanRuntime.

func NewPlanRuntimeWithClient

func NewPlanRuntimeWithClient(ctx context.Context, cfg *RuntimeConfig, c client.Client) (agentos.PlanRuntime, error)

NewPlanRuntimeWithClient adapts an existing Temporal client to agentos.PlanRuntime.

func NewProcessRuntime

func NewProcessRuntime(ctx context.Context, cfg *RuntimeConfig) (agentosproc.Runtime, error)

NewProcessRuntime creates the default Temporal implementation of agentosproc.Runtime.

func NewProcessRuntimeWithClient

func NewProcessRuntimeWithClient(ctx context.Context, cfg *RuntimeConfig, c client.Client) (agentosproc.Runtime, error)

NewProcessRuntimeWithClient adapts an existing Temporal client to agentosproc.Runtime.

func NewRuntime

func NewRuntime(ctx context.Context, cfg *RuntimeConfig, options ...RuntimeOption) (agentos.Runtime, error)

NewRuntime creates the default Temporal/Redis implementation of agentos.Runtime.

func NewRuntimeWithClient

func NewRuntimeWithClient(ctx context.Context, cfg *RuntimeConfig, c client.Client, options ...RuntimeOption) (agentos.Runtime, error)

NewRuntimeWithClient adapts an existing Temporal client to agentos.Runtime. Hosts that already own worker/client lifecycle can use this without opening another Temporal connection.

func PlanWorkflow

func PlanWorkflow(ctx workflow.Context, input *planWorkflowInput) (agentos.RunPlanStatus, error)

PlanWorkflow executes a cross-backend RunPlan using deterministic plan state and activity-backed backend I/O.

func ProcessWorkflow

func ProcessWorkflow(ctx workflow.Context, input *processWorkflowInput) (agentosproc.Status, error)

ProcessWorkflow runs one coarse-grained durable process for an application resource. It owns process lifecycle signals and timers, not backend internals.

func RegisterPlanActivities

func RegisterPlanActivities(w worker.Worker, activities *PlanActivities) error

RegisterPlanActivities installs AgentOS RunPlan activities into an existing worker.

func RegisterPlanWorkflow

func RegisterPlanWorkflow(w worker.Worker) error

RegisterPlanWorkflow installs the AgentOS RunPlan workflow into an existing worker.

func RegisterProcessActivities

func RegisterProcessActivities(w worker.Worker, activities *ProcessActivities) error

RegisterProcessActivities installs AgentOS process activities into an existing worker.

func RegisterProcessWorkflow

func RegisterProcessWorkflow(w worker.Worker) error

RegisterProcessWorkflow installs the AgentOS process workflow into an existing worker.

Types

type ArtifactStoreBackend

type ArtifactStoreBackend string
const (
	ArtifactStoreBackendLocal ArtifactStoreBackend = "local"
	ArtifactStoreBackendS3    ArtifactStoreBackend = "s3"
)

type ArtifactStoreConfig

type ArtifactStoreConfig struct {
	Backend ArtifactStoreBackend
	Local   LocalArtifactStoreConfig
	S3      S3ArtifactStoreConfig
}

ArtifactStoreConfig selects the blob store used for large AgentOS plan artifacts. Artifact metadata is still stored in the durable plan database.

type EvaluatePlanExpansionOutput

type EvaluatePlanExpansionOutput struct {
	Expanded           bool
	Delta              agentosplan.PlanDelta
	Spec               agentos.RunPlanSpec
	Plan               agentosplan.ExecutablePlan
	ControlsByNode     map[string][]agentoscore.ControlOperation
	CapabilitiesByNode map[string]agentosplan.CapabilitySelectionTrace
}

type ExternalBackendConfig

type ExternalBackendConfig struct {
	Name         string
	TaskQueue    string
	WorkflowType string
	QueryType    string
	Signals      ExternalSignalNames
}

ExternalBackendConfig configures a temporal_external AgentOS backend.

type ExternalSignalNames

type ExternalSignalNames struct {
	Pause    string
	Resume   string
	Cancel   string
	Defaults map[agentoscore.SignalType]string
}

ExternalSignalNames maps AgentOS signals and controls to external workflow signal names.

type GRPCBackendConfig

type GRPCBackendConfig struct {
	Name      string
	Target    string
	Authority string
	Insecure  bool
	Service   string
	Methods   GRPCMethodNames
}

GRPCBackendConfig configures a gRPC AgentOS backend.

type GRPCMethodNames

type GRPCMethodNames struct {
	Start   string
	Signal  string
	Control string
	Status  string
}

GRPCMethodNames maps AgentOS operations to external gRPC unary method names.

type HTTPBackendConfig

type HTTPBackendConfig struct {
	Name     string
	Endpoint string
	Headers  map[string]string
}

HTTPBackendConfig configures an HTTP AgentOS backend.

type LocalArtifactStoreConfig

type LocalArtifactStoreConfig struct {
	Root string
}

type PersistPlanStateOutput

type PersistPlanStateOutput struct {
	Event agentos.PlanEvent
}

type PlanActivities

type PlanActivities struct {
	Runtime             agentos.Runtime
	PlanNodeStarter     PlanNodeStarter
	Validator           agentosplan.Validator
	PlanTransitionStore agentosplan.PlanTransitionStore
	PlanEventPublisher  agentosplan.PlanEventPublisher
	ArtifactStore       agentosplan.ArtifactStore
	ArtifactSchemas     agentosplan.ArtifactSchemaCatalog
	PlanDeltaProvider   agentosplan.PlanDeltaProvider
	Expressions         agentosplan.ValueExpressionCompiler
}

PlanActivities bridge Temporal PlanWorkflow decisions to AgentOS runtime calls.

func NewPlanActivitiesWithCatalog

func NewPlanActivitiesWithCatalog(
	runtime agentos.Runtime,
	catalog agentosplan.CapabilityCatalog,
	transitionStore agentosplan.PlanTransitionStore,
	eventPublisher agentosplan.PlanEventPublisher,
	artifactStore agentosplan.ArtifactStore,
) (*PlanActivities, error)

NewPlanActivitiesWithCatalog creates plan activities with an explicit capability catalog. Production wiring should provide a durable catalog.

func NewPlanActivitiesWithCatalogAndSchemas

func NewPlanActivitiesWithCatalogAndSchemas(
	runtime agentos.Runtime,
	catalog agentosplan.CapabilityCatalog,
	artifactSchemas agentosplan.ArtifactSchemaCatalog,
	transitionStore agentosplan.PlanTransitionStore,
	eventPublisher agentosplan.PlanEventPublisher,
	artifactStore agentosplan.ArtifactStore,
) (*PlanActivities, error)

NewPlanActivitiesWithCatalogAndSchemas creates plan activities with explicit capability and artifact schema catalogs.

func NewPlanActivitiesWithStores

func NewPlanActivitiesWithStores(
	runtime agentos.Runtime,
	capabilities []agentos.Capability,
	transitionStore agentosplan.PlanTransitionStore,
	eventPublisher agentosplan.PlanEventPublisher,
	artifactStore agentosplan.ArtifactStore,
) (*PlanActivities, error)

NewPlanActivitiesWithStores creates plan activities with explicit durable state and event stores.

func (*PlanActivities) ControlPlanNodeActivity

func (a *PlanActivities) ControlPlanNodeActivity(ctx context.Context, input *controlPlanNodeInput) error

ControlPlanNodeActivity sends lifecycle control to one child run.

func (*PlanActivities) EvaluatePlanExpansionActivity

func (a *PlanActivities) EvaluatePlanExpansionActivity(ctx context.Context, input *evaluatePlanExpansionInput) (EvaluatePlanExpansionOutput, error)

EvaluatePlanExpansionActivity materializes and validates workflow-owned dynamic topology expansion after a child run publishes explicit plan_delta artifacts.

func (*PlanActivities) PersistPlanStateActivity

func (a *PlanActivities) PersistPlanStateActivity(ctx context.Context, input *persistPlanStateInput) (PersistPlanStateOutput, error)

PersistPlanStateActivity writes the latest reducer snapshot and appends the corresponding public PlanEvent to the durable event source.

func (*PlanActivities) PublishPlanArtifactsActivity

func (a *PlanActivities) PublishPlanArtifactsActivity(ctx context.Context, input *publishPlanArtifactsInput) (PublishPlanArtifactsOutput, error)

PublishPlanArtifactsActivity persists child-run artifact refs outside workflow history. Backends that produce payloads must write those payloads to the configured AgentOS ArtifactStore before returning refs; this activity only claims the ref idempotently and returns metadata to the workflow.

func (*PlanActivities) ResolvePlanNodeInputActivity

func (a *PlanActivities) ResolvePlanNodeInputActivity(ctx context.Context, input *resolvePlanNodeInputInput) (ResolvePlanNodeInputOutput, error)

ResolvePlanNodeInputActivity resolves node input mapping before a child run starts.

func (*PlanActivities) StartPlanNodeActivity

func (a *PlanActivities) StartPlanNodeActivity(ctx context.Context, input *startPlanNodeInput) (StartPlanNodeOutput, error)

StartPlanNodeActivity starts one backend-owned child run.

func (*PlanActivities) StatusPlanNodeActivity

func (a *PlanActivities) StatusPlanNodeActivity(ctx context.Context, input statusPlanNodeInput) (StatusPlanNodeOutput, error)

StatusPlanNodeActivity queries one backend-owned child run.

func (*PlanActivities) ValidatePlanActivity

func (a *PlanActivities) ValidatePlanActivity(ctx context.Context, input *validatePlanInput) (ValidatePlanOutput, error)

ValidatePlanActivity validates a RunPlan before workflow execution.

type PlanCommandRecoverer

type PlanCommandRecoverer interface {
	RecoverPlanCommands(ctx context.Context, limit int) (PlanCommandRecoveryResult, error)
}

PlanCommandRecoverer redelivers durable RunPlan command outbox records.

type PlanCommandRecoveryLoop

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

PlanCommandRecoveryLoop owns periodic recovery of pending/failed RunPlan command outbox records.

func StartPlanCommandRecovery

StartPlanCommandRecovery starts a background recovery loop.

func (*PlanCommandRecoveryLoop) Stop

func (l *PlanCommandRecoveryLoop) Stop()

Stop cancels the loop and waits for it to exit.

type PlanCommandRecoveryLoopConfig

type PlanCommandRecoveryLoopConfig struct {
	Interval           time.Duration
	Limit              int
	RecoverImmediately bool
}

PlanCommandRecoveryLoopConfig controls periodic durable command recovery.

type PlanCommandRecoveryObserver

type PlanCommandRecoveryObserver interface {
	PlanCommandRecoverySucceeded(PlanCommandRecoveryResult)
	PlanCommandRecoveryFailed(error)
}

PlanCommandRecoveryObserver receives recovery pass outcomes.

type PlanCommandRecoveryResult

type PlanCommandRecoveryResult struct {
	Scanned   int
	Delivered int
	Failed    int
}

PlanCommandRecoveryResult summarizes one durable command outbox recovery pass.

type PlanNodeStarter

type PlanNodeStarter interface {
	StartPlanNode(ctx context.Context, planID, nodeID string, spec *agentos.RunSpec) (agentos.RunStatus, error)
}

PlanNodeStarter starts backend-owned child runs and records plan-node route ownership atomically at the AgentOS runtime boundary.

type ProcessActivities

type ProcessActivities struct {
	Runtime *agentosprocess.Runtime
}

ProcessActivities bridge ProcessWorkflow decisions to the durable process store.

func NewProcessActivities

NewProcessActivities creates activities for generic durable processes.

func (*ProcessActivities) ControlProcessActivity

func (a *ProcessActivities) ControlProcessActivity(ctx context.Context, input *controlProcessActivityInput) (agentosproc.Status, error)

func (*ProcessActivities) FireProcessTimerActivity

func (a *ProcessActivities) FireProcessTimerActivity(ctx context.Context, input *fireProcessTimerActivityInput) (agentosproc.Status, error)

func (*ProcessActivities) SignalProcessActivity

func (a *ProcessActivities) SignalProcessActivity(ctx context.Context, input *signalProcessActivityInput) (agentosproc.Status, error)

func (*ProcessActivities) StartProcessActivity

func (a *ProcessActivities) StartProcessActivity(ctx context.Context, input *startProcessActivityInput) (agentosproc.Status, error)

type PublishPlanArtifactsOutput

type PublishPlanArtifactsOutput struct {
	Artifacts []agentoscore.ArtifactRef
}

type ResolvePlanNodeInputOutput

type ResolvePlanNodeInputOutput struct {
	Input map[string]any
	Trace agentosplan.InputResolutionTrace
}

type RunBackendIndex

type RunBackendIndex = agentosruntime.RunBackendIndex

RunBackendIndex persists run ownership for Signal/Control/Status routing.

type RunBackendSelector

type RunBackendSelector interface {
	Select(ctx context.Context, spec *agentos.RunSpec) (agentos.BackendRef, error)
}

RunBackendSelector resolves a backend when RunSpec.Backend is intentionally empty.

type RuntimeConfig

type RuntimeConfig struct {
	TemporalAddress          string
	TemporalNamespace        string
	TemporalTaskQueues       TaskQueues
	PostgresURL              string
	PostgresPoolMax          int
	RedisURL                 string
	ArtifactStore            ArtifactStoreConfig
	TemporalExternalBackends []ExternalBackendConfig
	HTTPBackends             []HTTPBackendConfig
	GRPCBackends             []GRPCBackendConfig
}

RuntimeConfig configures the default Temporal/Redis runtime implementation.

type RuntimeOption

type RuntimeOption func(*runtimeOptions)

RuntimeOption customizes runtime construction.

func WithRunBackendIndex

func WithRunBackendIndex(index RunBackendIndex) RuntimeOption

WithRunBackendIndex provides a durable run -> backend route index.

func WithRunBackendSelector

func WithRunBackendSelector(selector RunBackendSelector) RuntimeOption

WithRunBackendSelector installs an optional backend policy resolver.

type S3ArtifactStoreConfig

type S3ArtifactStoreConfig struct {
	Bucket          string
	Region          string
	Endpoint        string
	AccessKeyID     string
	SecretAccessKey string
	SessionToken    string
	ForcePathStyle  bool
}

type StartPlanNodeOutput

type StartPlanNodeOutput struct {
	Status agentos.RunStatus
}

type StatusPlanNodeOutput

type StatusPlanNodeOutput struct {
	Status agentos.RunStatus
}

type TaskQueues

type TaskQueues struct {
	PlanControl     string
	PlanActivity    string
	ProcessControl  string
	ProcessActivity string
	NativeControl   string
	NativeLLM       string
	NativeTool      string
	Stream          string
	Trigger         string
}

TaskQueues names the Temporal queues used by the default AgentOS Temporal implementation.

func DefaultTaskQueues

func DefaultTaskQueues() TaskQueues

DefaultTaskQueues returns the production-oriented AgentOS queue split.

func (*TaskQueues) Validate

func (q *TaskQueues) Validate() error

Validate ensures every workload class has an explicit, distinct queue.

type ValidatePlanOutput

type ValidatePlanOutput struct {
	Plan               agentosplan.ExecutablePlan
	ControlsByNode     map[string][]agentoscore.ControlOperation
	CapabilitiesByNode map[string]agentosplan.CapabilitySelectionTrace
}

type WorkerConfig

type WorkerConfig struct {
	TemporalAddress    string
	TemporalNamespace  string
	TemporalTaskQueues TaskQueues
	PostgresURL        string
	PostgresPoolMax    int
	RedisURL           string
	LLMConfigPath      string
	LogLevel           string
	ArtifactStore      ArtifactStoreConfig

	TemporalExternalBackends []ExternalBackendConfig
	HTTPBackends             []HTTPBackendConfig
	GRPCBackends             []GRPCBackendConfig
	Capabilities             []agentos.Capability
	ArtifactSchemas          []agentos.ArtifactSchema

	RegisterEnvTools      bool
	EnsureDefaultTemplate bool
}

WorkerConfig configures registration of GoAgent workflows and activities into a Temporal worker.

type WorkerKit

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

WorkerKit registers GoAgent workflows and activities into explicit workload workers.

func NewWorkerKit

func NewWorkerKit(ctx context.Context, cfg *WorkerConfig) (*WorkerKit, error)

NewWorkerKit creates a worker registration kit backed by the default Temporal/Postgres/Redis/Bifrost implementation.

func (*WorkerKit) Close

func (k *WorkerKit) Close() error

Close releases resources owned by the kit.

func (*WorkerKit) RecoverPlanCommands

func (k *WorkerKit) RecoverPlanCommands(ctx context.Context, limit int) (PlanCommandRecoveryResult, error)

RecoverPlanCommands redelivers pending/failed RunPlan control-plane commands from the durable outbox.

func (*WorkerKit) Register

func (k *WorkerKit) Register(workers *WorkerSet) error

Register installs workflow definitions and activities into explicit workers.

func (*WorkerKit) StartPlanCommandRecovery

StartPlanCommandRecovery starts periodic durable command outbox recovery for this worker kit.

type WorkerSet

type WorkerSet struct {
	PlanControl     worker.Worker
	PlanActivity    worker.Worker
	ProcessControl  worker.Worker
	ProcessActivity worker.Worker
	NativeControl   worker.Worker
	NativeLLM       worker.Worker
	NativeTool      worker.Worker
	Stream          worker.Worker
	Trigger         worker.Worker
}

WorkerSet contains one Temporal worker per workload class.

Jump to

Keyboard shortcuts

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