execution

Documentation

Overview

Package runtime defines the execution interfaces for openbotstack-core.

These interfaces are defined in core but implemented in openbotstack-runtime. This ensures the control plane can declare execution requirements without depending on runtime implementation details.

Index

• Variables
• type CircuitBreaker
• type CircuitState
• type ExecutionContext
  • func NewExecutionContext(ctx context.Context, reqID, asstID, sessionID, tenantID, userID string) *ExecutionContext
  • func (ec *ExecutionContext) AddResult(res StepResult)
  • func (ec *ExecutionContext) Results() []StepResult
• type ExecutionLogRecord
• type ExecutionLogger
• type ExecutionPlan
  • func (p *ExecutionPlan) Validate() error
• type ExecutionRequest
• type ExecutionResult
• type ExecutionStatus
• type ExecutionStep
  • func (s *ExecutionStep) ArgumentsJSON() ([]byte, error)
• type ResourceUsage
• type SkillExecutor
• type StepResult
• type StepType

Variables

var (
	// ErrSkillNotLoaded is returned when executing an unloaded skills.
	ErrSkillNotLoaded = errors.New("runtime: skill not loaded")

	// ErrExecutionTimeout is returned when execution exceeds timeout.
	ErrExecutionTimeout = errors.New("runtime: execution timeout")

	// ErrCircuitOpen is returned when the circuit breaker is open.
	ErrCircuitOpen = errors.New("runtime: circuit breaker open")

	// ErrResourceExhausted is returned when resource limits are exceeded.
	ErrResourceExhausted = errors.New("runtime: resource exhausted")

	// ErrPolicyRejected is returned when policy denies execution.
	ErrPolicyRejected = errors.New("runtime: policy rejected execution")
)

Types

type CircuitBreaker

type CircuitBreaker interface {
	// Allow checks if the circuit allows execution.
	Allow(ctx context.Context, skillID string) (bool, error)

	// RecordSuccess records a successful execution.
	RecordSuccess(ctx context.Context, skillID string)

	// RecordFailure records a failed execution.
	RecordFailure(ctx context.Context, skillID string)

	// State returns the current circuit state.
	State(ctx context.Context, skillID string) (CircuitState, error)
}

CircuitBreaker prevents cascading failures in execution.

type CircuitState

type CircuitState string

CircuitState indicates the circuit breaker state.

const (
	CircuitClosed   CircuitState = "closed"    // normal operation
	CircuitOpen     CircuitState = "open"      // blocking requests
	CircuitHalfOpen CircuitState = "half_open" // testing recovery
)

type ExecutionContext

type ExecutionContext struct {
	// Standard context for cancellation/timeout
	context.Context

	// Request Identity
	RequestID   string
	AssistantID string
	SessionID   string
	TenantID    string
	UserID      string

	// Execution bounds
	StartedAt time.Time
	Deadline  time.Time
	// contains filtered or unexported fields
}

ExecutionContext holds the request-scoped state for an execution plan. It tracks limits, identities, and the accumulated results of steps.

func NewExecutionContext

func NewExecutionContext(ctx context.Context, reqID, asstID, sessionID, tenantID, userID string) *ExecutionContext

NewExecutionContext creates a new execution context to track a multi-step execution.

func (*ExecutionContext) AddResult

func (ec *ExecutionContext) AddResult(res StepResult)

AddResult appends a step result to the execution history in a thread-safe manner.

func (*ExecutionContext) Results

func (ec *ExecutionContext) Results() []StepResult

Results returns a copy of all accumulated step results.

type ExecutionLogRecord

type ExecutionLogRecord struct {
	RequestID   string        `json:"request_id"`
	AssistantID string        `json:"assistant_id"`
	StepName    string        `json:"step_name"`
	StepType    string        `json:"step_type"`
	Status      string        `json:"status"`
	Output      any           `json:"output,omitempty"`
	Error       string        `json:"error,omitempty"`
	Duration    time.Duration `json:"duration_ms"`
	Timestamp   time.Time     `json:"timestamp"`
}

ExecutionLogRecord represents a single log entry for an execution step.

type ExecutionLogger

type ExecutionLogger interface {
	// LogStep records the result of a single step.
	LogStep(ctx context.Context, record ExecutionLogRecord) error

	// LogPlanStart records the beginning of a multi-step plan.
	LogPlanStart(ctx context.Context, requestID, assistantID string, plan ExecutionPlan) error

	// LogPlanEnd records the completion of a multi-step plan.
	LogPlanEnd(ctx context.Context, requestID, assistantID string, err error) error
}

ExecutionLogger defines the interface for recording execution events.

type ExecutionPlan

type ExecutionPlan struct {
	AssistantID string          `json:"assistant_id"`
	Steps       []ExecutionStep `json:"steps"`
	Reasoning   string          `json:"reasoning,omitempty"`
}

ExecutionPlan specifies a sequence of steps to achieve a goal.

func (*ExecutionPlan) Validate

func (p *ExecutionPlan) Validate() error

Validate checks if the execution plan is well-formed.

type ExecutionRequest

type ExecutionRequest struct {
	// SkillID identifies the skill to execute.
	SkillID string

	// Input is the JSON input to the skills.
	Input []byte

	// Timeout overrides the skill's default timeout.
	Timeout time.Duration

	// TenantID for resource isolation.
	TenantID string

	// UserID for audit logging.
	UserID string

	// RequestID for tracing.
	RequestID string
}

ExecutionRequest is the input to skill execution.

type ExecutionResult

type ExecutionResult struct {
	// Output is the JSON output from the skills.
	Output []byte

	// Error is the error message if execution failed.
	Error string

	// Status indicates execution outcome.
	Status ExecutionStatus

	// Duration is the actual execution time.
	Duration time.Duration

	// ResourceUsage tracks consumed resources.
	ResourceUsage ResourceUsage
}

ExecutionResult is the output from skill execution.

type ExecutionStatus

type ExecutionStatus string

ExecutionStatus indicates the outcome of execution.

const (
	StatusSuccess  ExecutionStatus = "success"
	StatusFailed   ExecutionStatus = "failed"
	StatusTimeout  ExecutionStatus = "timeout"
	StatusCanceled ExecutionStatus = "canceled"
	StatusRejected ExecutionStatus = "rejected" // policy denied
)

type ExecutionStep

type ExecutionStep struct {
	Name      string         `json:"name"`
	Type      StepType       `json:"type"`
	Arguments map[string]any `json:"arguments"`
}

ExecutionStep represents a single action in an execution plan.

func (*ExecutionStep) ArgumentsJSON

func (s *ExecutionStep) ArgumentsJSON() ([]byte, error)

ArgumentsJSON returns the arguments serialized as JSON bytes.

type ResourceUsage

type ResourceUsage struct {
	CPUTimeMs  int64
	MemoryMB   int64
	TokensUsed int64
}

ResourceUsage tracks execution resource consumption.

type SkillExecutor

type SkillExecutor interface {
	// Execute runs a skill with the given input.
	Execute(ctx context.Context, req ExecutionRequest) (*ExecutionResult, error)

	// CanExecute checks if the skill can be executed.
	CanExecute(ctx context.Context, skillID string) (bool, error)

	// LoadSkill prepares a skill for execution.
	LoadSkill(ctx context.Context, pkg skills.Skill) error

	// ExecutePlan runs a multi-step execution plan using the provided context.
	ExecutePlan(ctx context.Context, plan *ExecutionPlan, ec *ExecutionContext) error
}

SkillExecutor executes skills in a sandboxed environment.

This interface is defined in core but implemented in runtime.

type StepResult

type StepResult struct {
	StepName string
	Type     string // "skill" or "tool"
	Output   any
	Error    error
	Duration time.Duration
}

StepResult represents the outcome of a single execution step (skill or tool).

type StepType

type StepType string

StepType indicates whether a step is a skill or a tool.

const (
	StepTypeSkill StepType = "skill"
	StepTypeTool  StepType = "tool"
)