model

package
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: May 27, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package model defines the transport-agnostic automation domain model shared by configuration, persistence, runtime, and API layers.

Index

Constants

View Source 
const DefaultMaxConcurrentJobs = 5

DefaultMaxConcurrentJobs is the default global automation concurrency limit.

View Source 
const DefaultTimezone = "UTC"

DefaultTimezone is the default schedule timezone used by automation config.

Variables

View Source 
var (
	// ErrJobNotFound reports that the requested automation job does not exist.
	ErrJobNotFound = errors.New("automation: job not found")
	// ErrTriggerNotFound reports that the requested automation trigger does not exist.
	ErrTriggerNotFound = errors.New("automation: trigger not found")
	// ErrRunNotFound reports that the requested automation run does not exist.
	ErrRunNotFound = errors.New("automation: run not found")
	// ErrRunAlreadyExists reports that an automation run identity has already been claimed.
	ErrRunAlreadyExists = errors.New("automation: run already exists")
	// ErrSchedulerStateNotFound reports that no durable scheduler cursor exists for a job.
	ErrSchedulerStateNotFound = errors.New("automation: scheduler state not found")
	// ErrScheduledFireAlreadyClaimed reports that a scheduled fire identity was already claimed.
	ErrScheduledFireAlreadyClaimed = errors.New("automation: scheduled fire already claimed")
	// ErrJobNameTaken reports a duplicate job name within the same automation scope.
	ErrJobNameTaken = errors.New("automation: job name already exists in scope")
	// ErrTriggerNameTaken reports a duplicate trigger name within the same automation scope.
	ErrTriggerNameTaken = errors.New("automation: trigger name already exists in scope")
	// ErrTriggerWebhookIDTaken reports a duplicate stable webhook identifier.
	ErrTriggerWebhookIDTaken = errors.New("automation: trigger webhook id already exists")
	// ErrOverlayRequiresConfigSource reports that enabled overlays only apply to config- or package-backed definitions.
	ErrOverlayRequiresConfigSource = errors.New("automation: enabled overlays require config or package source")
	// ErrJobOverlayNotFound reports that a job enabled overlay row does not exist.
	ErrJobOverlayNotFound = errors.New("automation: job enabled overlay not found")
	// ErrTriggerOverlayNotFound reports that a trigger enabled overlay row does not exist.
	ErrTriggerOverlayNotFound = errors.New("automation: trigger enabled overlay not found")
)

Functions

func ParseTriggerPromptTemplate 

func ParseTriggerPromptTemplate(prompt string) (*template.Template, error)

ParseTriggerPromptTemplate parses a trigger prompt template with strict activation-envelope validation.

func ValidateScopeBinding 

func ValidateScopeBinding(scope Scope, workspaceBinding string, path string, workspaceField string) error

ValidateScopeBinding enforces the global/workspace binding invariants shared by jobs, triggers, and envelopes.

func ValidateTriggerFilter 

func ValidateTriggerFilter(filter map[string]string, path string) error

ValidateTriggerFilter ensures trigger filters only reference supported activation-envelope field paths.

func ValidateTriggerPromptTemplate 

func ValidateTriggerPromptTemplate(prompt string) error

ValidateTriggerPromptTemplate validates a trigger prompt template against the normalized activation-envelope model.

Types

type ActivationEnvelope 

type ActivationEnvelope struct {
	Kind        string           `json:"kind"`
	Scope       Scope            `json:"scope"`
	WorkspaceID string           `json:"workspace_id,omitempty"`
	Source      ActivationSource `json:"source"`
	Data        map[string]any   `json:"data"`
}

ActivationEnvelope is the normalized trigger input regardless of source.

func (ActivationEnvelope) Validate 

func (e ActivationEnvelope) Validate(path string) error

Validate ensures the normalized activation envelope satisfies the shared scope and source invariants.

type ActivationSource 

type ActivationSource string

ActivationSource identifies which ingress path produced an activation envelope. 

const (
	// ActivationSourceObserver identifies observer-backed trigger ingress.
	ActivationSourceObserver ActivationSource = "observer"
	// ActivationSourceHook identifies hook-backed trigger ingress.
	ActivationSourceHook ActivationSource = "hook"
	// ActivationSourceWebhook identifies external webhook ingress.
	ActivationSourceWebhook ActivationSource = "webhook"
	// ActivationSourceExtension identifies extension-provided ingress.
	ActivationSourceExtension ActivationSource = "extension"
)

func (ActivationSource) Validate 

func (s ActivationSource) Validate(path string) error

Validate ensures the activation source is one of the supported ingress values.

type FireLimitConfig 

type FireLimitConfig struct {
	Max    int    `json:"max"    toml:"max"`
	Window string `json:"window" toml:"window"`
}

FireLimitConfig caps how often a job or trigger may fire within a rolling window.

func DefaultFireLimitConfig 

func DefaultFireLimitConfig() FireLimitConfig

DefaultFireLimitConfig returns the default rolling fire-limit policy.

func (FireLimitConfig) Validate 

func (c FireLimitConfig) Validate(path string) error

Validate ensures the rolling fire-limit configuration is internally consistent.

type Job 

type Job struct {
	ID          string          `json:"id"`
	Scope       Scope           `json:"scope"`
	Name        string          `json:"name"`
	AgentName   string          `json:"agent_name"`
	WorkspaceID string          `json:"workspace_id,omitempty"`
	Prompt      string          `json:"prompt"`
	Schedule    *ScheduleSpec   `json:"schedule,omitempty"`
	Task        *JobTaskConfig  `json:"task,omitempty"`
	Enabled     bool            `json:"enabled"`
	Retry       RetryConfig     `json:"retry"`
	FireLimit   FireLimitConfig `json:"fire_limit"`
	Source      JobSource       `json:"source"`
	CreatedAt   time.Time       `json:"created_at"`
	UpdatedAt   time.Time       `json:"updated_at"`
}

Job is the canonical scheduled automation definition used by runtime and storage layers.

func (Job) Validate 

func (j Job) Validate(path string) error

Validate ensures the scheduled job definition is internally consistent.

type JobEnabledOverlay 

type JobEnabledOverlay struct {
	JobID           string    `json:"job_id"`
	EnabledOverride bool      `json:"enabled_override"`
	UpdatedAt       time.Time `json:"updated_at"`
}

JobEnabledOverlay stores the runtime enabled override for a config-backed job.

type JobListQuery 

type JobListQuery struct {
	Scope       Scope     `json:"scope,omitempty"`
	WorkspaceID string    `json:"workspace_id,omitempty"`
	Source      JobSource `json:"source,omitempty"`
	Limit       int       `json:"limit,omitempty"`
}

JobListQuery filters persisted automation job listings.

type JobSource 

type JobSource string

JobSource identifies where a job or trigger definition originated. 

const (
	// JobSourceConfig identifies a TOML-backed automation definition.
	JobSourceConfig JobSource = "config"
	// JobSourcePackage identifies a daemon-managed extension bundle definition.
	JobSourcePackage JobSource = "package"
	// JobSourceDynamic identifies a runtime-created automation definition.
	JobSourceDynamic JobSource = "dynamic"
)

func (JobSource) Validate 

func (s JobSource) Validate(path string) error

Validate ensures the source is one of the supported automation source values.

type JobTaskConfig 

type JobTaskConfig struct {
	Title          string             `json:"title,omitempty"           toml:"title,omitempty"`
	Description    string             `json:"description,omitempty"     toml:"description,omitempty"`
	Owner          *taskpkg.Ownership `json:"owner,omitempty"           toml:"owner,omitempty"`
	NetworkChannel string             `json:"network_channel,omitempty" toml:"network_channel,omitempty"`
}

JobTaskConfig configures direct automation-to-task materialization for one job.

func (JobTaskConfig) Validate 

func (c JobTaskConfig) Validate(path string) error

Validate ensures the direct task materialization configuration is internally consistent.

type RetryConfig 

type RetryConfig struct {
	Strategy   RetryStrategy `json:"strategy"    toml:"strategy"`
	MaxRetries int           `json:"max_retries" toml:"max_retries"`
	BaseDelay  string        `json:"base_delay"  toml:"base_delay"`
}

RetryConfig defines retry behavior for a failed automation run.

func DefaultBackoffRetryConfig 

func DefaultBackoffRetryConfig() RetryConfig

DefaultBackoffRetryConfig returns the default exponential backoff retry policy.

func DefaultRetryConfig 

func DefaultRetryConfig() RetryConfig

DefaultRetryConfig returns the default retry policy for automation definitions.

func (RetryConfig) Validate 

func (c RetryConfig) Validate(path string) error

Validate ensures the retry configuration is internally consistent.

type RetryStrategy 

type RetryStrategy string

RetryStrategy identifies how failed runs should be retried. 

const (
	// RetryStrategyNone disables retries after a failed run.
	RetryStrategyNone RetryStrategy = "none"
	// RetryStrategyBackoff retries failed runs with exponential backoff.
	RetryStrategyBackoff RetryStrategy = "backoff"
)

func (RetryStrategy) Validate 

func (s RetryStrategy) Validate(path string) error

Validate ensures the retry strategy is supported.

type Run 

type Run struct {
	ID              string     `json:"id"`
	JobID           string     `json:"job_id,omitempty"`
	TriggerID       string     `json:"trigger_id,omitempty"`
	SessionID       string     `json:"session_id,omitempty"`
	TaskID          string     `json:"task_id,omitempty"`
	TaskRunID       string     `json:"task_run_id,omitempty"`
	FireID          string     `json:"fire_id,omitempty"`
	Status          RunStatus  `json:"status"`
	Attempt         int        `json:"attempt"`
	ScheduledAt     *time.Time `json:"scheduled_at,omitempty"`
	StartedAt       *time.Time `json:"started_at,omitempty"`
	EndedAt         *time.Time `json:"ended_at,omitempty"`
	Error           string     `json:"error,omitempty"`
	DeliveryError   string     `json:"delivery_error,omitempty"`
	DeliveryErrorAt *time.Time `json:"delivery_error_at,omitempty"`
}

Run records the execution state of a single automation fire.

func (Run) Validate 

func (r Run) Validate(path string) error

Validate ensures the run record is internally consistent.

type RunQuery 

type RunQuery struct {
	JobID     string    `json:"job_id,omitempty"`
	TriggerID string    `json:"trigger_id,omitempty"`
	Status    RunStatus `json:"status,omitempty"`
	ExcludeID string    `json:"exclude_id,omitempty"`
	Since     time.Time `json:"since"`
	Until     time.Time `json:"until"`
	Limit     int       `json:"limit,omitempty"`
}

RunQuery filters automation run history and fire-limit window lookups.

type RunStatus 

type RunStatus string

RunStatus identifies the current lifecycle state of an automation run. 

const (
	// RunScheduled reports a run that has been accepted but not yet started.
	RunScheduled RunStatus = "scheduled"
	// RunRunning reports a run that is actively dispatching or executing.
	RunRunning RunStatus = "running"
	// RunDelegated reports an automation activation that delegated execution into the task domain.
	RunDelegated RunStatus = "delegated"
	// RunCompleted reports a run that finished successfully.
	RunCompleted RunStatus = "completed"
	// RunFailed reports a run that finished with an error.
	RunFailed RunStatus = "failed"
	// RunCancelled reports a run that was canceled before completion.
	RunCancelled RunStatus = "canceled"
)

func (RunStatus) Validate 

func (s RunStatus) Validate(path string) error

Validate ensures the run status is one of the supported lifecycle states.

type ScheduleMode 

type ScheduleMode string

ScheduleMode identifies how a scheduled job determines its next fire time. 

const (
	// ScheduleModeCron evaluates a cron expression.
	ScheduleModeCron ScheduleMode = "cron"
	// ScheduleModeEvery evaluates a Go duration interval.
	ScheduleModeEvery ScheduleMode = "every"
	// ScheduleModeAt evaluates a one-shot RFC3339 timestamp.
	ScheduleModeAt ScheduleMode = "at"
)

func (ScheduleMode) Validate 

func (m ScheduleMode) Validate(path string) error

Validate ensures the schedule mode is one of the supported scheduling modes.

type ScheduleSpec 

type ScheduleSpec struct {
	Mode     ScheduleMode `json:"mode"               toml:"mode"`
	Expr     string       `json:"expr,omitempty"     toml:"expr,omitempty"`
	Interval string       `json:"interval,omitempty" toml:"interval,omitempty"`
	Time     string       `json:"time,omitempty"     toml:"time,omitempty"`
}

ScheduleSpec describes how a job should be scheduled.

func (ScheduleSpec) Validate 

func (s ScheduleSpec) Validate(path string) error

Validate ensures the schedule spec matches the selected mode and has a valid expression payload.

type SchedulerCatchUpPolicy 

type SchedulerCatchUpPolicy string

SchedulerCatchUpPolicy identifies how missed scheduled fires are reconciled after daemon downtime. 

const (
	// SchedulerCatchUpPolicySkipMissed records missed fires as misfires and
	// advances to the next future cursor without dispatching stale work.
	SchedulerCatchUpPolicySkipMissed SchedulerCatchUpPolicy = "skip_missed"
)

func (SchedulerCatchUpPolicy) Validate 

func (p SchedulerCatchUpPolicy) Validate(path string) error

Validate ensures the scheduler catch-up policy is supported.

type SchedulerClaim 

type SchedulerClaim struct {
	JobID        string
	RunID        string
	FireID       string
	ScheduledAt  time.Time
	NextRunAt    *time.Time
	ClaimedAt    time.Time
	ScheduleHash string
}

SchedulerClaim reserves one scheduled fire after the durable cursor has been advanced.

func (SchedulerClaim) Validate 

func (c SchedulerClaim) Validate(path string) error

Validate ensures a scheduled fire claim can be persisted atomically.

type SchedulerClaimResult 

type SchedulerClaimResult struct {
	State SchedulerState
	Run   Run
}

SchedulerClaimResult reports the state and pre-created run for one claimed scheduled fire.

type SchedulerState 

type SchedulerState struct {
	JobID                     string                 `json:"job_id"`
	NextRunAt                 *time.Time             `json:"next_run_at,omitempty"`
	LastRunAt                 *time.Time             `json:"last_run_at,omitempty"`
	LastScheduledAt           *time.Time             `json:"last_scheduled_at,omitempty"`
	LastFireID                string                 `json:"last_fire_id,omitempty"`
	ScheduleHash              string                 `json:"schedule_hash,omitempty"`
	CatchUpPolicy             SchedulerCatchUpPolicy `json:"catch_up_policy"`
	MisfireGraceSeconds       int                    `json:"misfire_grace_seconds"`
	ConsecutiveResumeFailures int                    `json:"consecutive_resume_failures"`
	LastMisfireAt             *time.Time             `json:"last_misfire_at,omitempty"`
	MisfireCount              int                    `json:"misfire_count"`
	UpdatedAt                 time.Time              `json:"updated_at"`
}

SchedulerState stores the durable scheduling cursor for one automation job.

func (SchedulerState) Validate 

func (s SchedulerState) Validate(path string) error

Validate ensures the durable scheduler cursor is internally consistent.

type Scope 

type Scope string

Scope identifies the visibility boundary of an automation resource. 

const (
	// AutomationScopeGlobal targets daemon-wide automation without a workspace binding.
	AutomationScopeGlobal Scope = "global"
	// AutomationScopeWorkspace targets automation bound to a specific workspace.
	AutomationScopeWorkspace Scope = "workspace"
)

func (Scope) Validate 

func (s Scope) Validate(path string) error

Validate ensures the scope is one of the supported automation scope values.

type Trigger 

type Trigger struct {
	ID               string            `json:"id"`
	Scope            Scope             `json:"scope"`
	Name             string            `json:"name"`
	AgentName        string            `json:"agent_name"`
	WorkspaceID      string            `json:"workspace_id,omitempty"`
	Prompt           string            `json:"prompt"`
	Event            string            `json:"event"`
	Filter           map[string]string `json:"filter,omitempty"`
	Enabled          bool              `json:"enabled"`
	Retry            RetryConfig       `json:"retry"`
	FireLimit        FireLimitConfig   `json:"fire_limit"`
	Source           JobSource         `json:"source"`
	WebhookID        string            `json:"webhook_id,omitempty"`
	EndpointSlug     string            `json:"endpoint_slug,omitempty"`
	WebhookSecretRef string            `json:"webhook_secret_ref,omitempty"`
	CreatedAt        time.Time         `json:"created_at"`
	UpdatedAt        time.Time         `json:"updated_at"`
}

Trigger is the canonical event-driven automation definition used by runtime and storage layers.

func (Trigger) Validate 

func (t Trigger) Validate(path string) error

Validate ensures the trigger definition is internally consistent.

type TriggerEnabledOverlay 

type TriggerEnabledOverlay struct {
	TriggerID       string    `json:"trigger_id"`
	EnabledOverride bool      `json:"enabled_override"`
	UpdatedAt       time.Time `json:"updated_at"`
}

TriggerEnabledOverlay stores the runtime enabled override for a config-backed trigger.

type TriggerListQuery 

type TriggerListQuery struct {
	Scope       Scope     `json:"scope,omitempty"`
	WorkspaceID string    `json:"workspace_id,omitempty"`
	Event       string    `json:"event,omitempty"`
	Source      JobSource `json:"source,omitempty"`
	Limit       int       `json:"limit,omitempty"`
}

TriggerListQuery filters persisted automation trigger listings.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.