model

package
v0.3.0-beta.22 Latest Latest
Warning

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

Go to latest
Published: Sep 1, 2026 License: MIT Imports: 14 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 (
	// DefaultListLimit bounds automation list responses when callers omit a limit.
	DefaultListLimit = 50
	// MaxListLimit bounds one automation list response.
	MaxListLimit = 200
)
View Source
const (
	TriggerEventSessionCreated     = "session.created"
	TriggerEventSessionStopped     = "session.stopped"
	TriggerEventMemoryConsolidated = "memory.consolidated"
	TriggerEventWebhook            = "webhook"
)

Built-in activation event names the runtime emits for triggers. Hook completions use the `hook.<hook_name>.completed` pattern and extension events use the open `ext.*` namespace; every other name must match one of these constants or no producer will ever fire the trigger.

View Source
const DefaultMaxConcurrentJobs = 5

DefaultMaxConcurrentJobs is the default global automation concurrency limit.

View Source
const DefaultSuggestionPendingCap = 5

DefaultSuggestionPendingCap bounds unresolved suggestions per scope.

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")
	// ErrRunReservationConflict reports that an existing run changed before dispatch activation.
	ErrRunReservationConflict = errors.New("automation: run reservation conflict")
	// 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")
)
View Source
var (
	ErrSuggestionNotFound   = errors.New("automation: suggestion not found")
	ErrSuggestionResolved   = errors.New("automation: suggestion already resolved")
	ErrSuggestionPendingCap = errors.New("automation: suggestion pending cap reached")
)
View Source
var (
	// ErrListCursorInvalid reports a malformed cursor or one reused with different filters.
	ErrListCursorInvalid = errors.New("automation: list cursor is invalid")
)
View Source
var ErrWebhookEndpointInvalid = errors.New("automation: invalid webhook endpoint")

ErrWebhookEndpointInvalid reports that a webhook endpoint value cannot be normalized.

Functions

func EncodeJobListCursor

func EncodeJobListCursor(query JobListQuery, position ListCursorPosition) (string, error)

EncodeJobListCursor binds a stable anchor to the normalized job query.

func EncodeTriggerListCursor

func EncodeTriggerListCursor(query TriggerListQuery, position ListCursorPosition) (string, error)

EncodeTriggerListCursor binds a stable anchor to the normalized trigger query.

func FormatWebhookEndpoint

func FormatWebhookEndpoint(endpointSlug string, webhookID string) (string, error)

FormatWebhookEndpoint returns the stable public endpoint segment for one webhook registration.

func JobMatchesListQuery

func JobMatchesListQuery(job Job, query JobListQuery) bool

JobMatchesListQuery reports whether one job belongs to a public catalog query.

func ListSourceRank

func ListSourceRank(source JobSource) int

ListSourceRank returns the stable source precedence used by every automation catalog.

func NormalizeDirectTaskParticipation

func NormalizeDirectTaskParticipation(
	request *participation.Request,
) (*participation.Request, error)

NormalizeDirectTaskParticipation returns canonical authored participation for an Automation job that materializes a Task directly.

func ParseTriggerPromptTemplate

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

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

func SortJobsForList

func SortJobsForList(jobs []Job)

SortJobsForList orders jobs by source precedence, name, and id.

func SortTriggersForList

func SortTriggersForList(triggers []Trigger)

SortTriggersForList orders triggers by source precedence, name, and id.

func TriggerMatchesListQuery

func TriggerMatchesListQuery(trigger Trigger, query TriggerListQuery) bool

TriggerMatchesListQuery reports whether one trigger belongs to a public catalog query.

func ValidateDirectTaskParticipationScope

func ValidateDirectTaskParticipationScope(
	scope Scope,
	request *participation.Request,
	participationPath string,
	scopePath string,
) error

ValidateDirectTaskParticipationScope rejects Live participation when a direct Automation task has no workspace binding.

func ValidateJobListQuery

func ValidateJobListQuery(query JobListQuery) error

ValidateJobListQuery validates filters and cursor binding for a job query.

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 ValidateTriggerEvent

func ValidateTriggerEvent(event string, path string) error

ValidateTriggerEvent rejects event names no activation producer emits, so a trigger cannot be created permanently dead. Built-in names are closed; hook completions require a hook name; extension events require a suffix after the `ext.` namespace prefix. Surrounding whitespace is rejected so stored triggers stay canonical, matching the extension ingress contract.

func ValidateTriggerFilter

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

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

func ValidateTriggerListQuery

func ValidateTriggerListQuery(query TriggerListQuery) error

ValidateTriggerListQuery validates filters and cursor binding for a trigger query.

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"`
	ProfileID   string          `json:"profile_id"`
	Scope       Scope           `json:"scope"`
	Name        string          `json:"name"`
	TargetKind  TargetKind      `json:"target_kind"`
	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"`
	LoopTarget  *LoopTarget     `json:"loop_target,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) IsLoopTarget

func (j Job) IsLoopTarget() bool

IsLoopTarget reports whether the job delegates to a Loop.

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 JobListPage

type JobListPage struct {
	Jobs       []Job  `json:"jobs"`
	Total      int    `json:"total"`
	Limit      int    `json:"limit"`
	HasMore    bool   `json:"has_more"`
	NextCursor string `json:"next_cursor,omitempty"`
}

JobListPage is one stable page of automation jobs.

func BuildJobListPage

func BuildJobListPage(jobs []Job, query JobListQuery) (JobListPage, error)

BuildJobListPage applies canonical job filters, ordering, and cursor pagination.

type JobListQuery

type JobListQuery struct {
	ReadScope   store.ReadScope `json:"read_scope"`
	Scope       Scope           `json:"scope,omitempty"`
	WorkspaceID string          `json:"workspace_id,omitempty"`
	Source      JobSource       `json:"source,omitempty"`
	LoopName    string          `json:"loop_name,omitempty"`
	Enabled     *bool           `json:"enabled,omitempty"`
	Search      string          `json:"q,omitempty"`
	Cursor      string          `json:"cursor,omitempty"`
	Limit       int             `json:"limit,omitempty"`
}

JobListQuery filters persisted automation job listings.

func JobListQueryWithDefaultLimit

func JobListQueryWithDefaultLimit(query JobListQuery) JobListQuery

JobListQueryWithDefaultLimit normalizes a public job query and applies the default page size.

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 definition managed by an extension package.
	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"`
	NetworkParticipation *participation.Request `json:"network_participation,omitempty" toml:"network_participation,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 ListCursorPosition

type ListCursorPosition struct {
	Source JobSource `json:"s"`
	Name   string    `json:"n"`
	ID     string    `json:"i"`
}

ListCursorPosition is the stable source/name/id anchor carried by automation list cursors.

func JobListCursor

func JobListCursor(query JobListQuery) (ListCursorPosition, bool, error)

JobListCursor decodes the optional cursor after validating its job-query fingerprint.

func TriggerListCursor

func TriggerListCursor(query TriggerListQuery) (ListCursorPosition, bool, error)

TriggerListCursor decodes the optional cursor after validating its trigger-query fingerprint.

type LoopTarget

type LoopTarget struct {
	WorkspaceID string `json:"workspace_id" toml:"workspace_id"`

	LoopName string `json:"loop_name" toml:"loop_name"`

	Inputs map[string]any `json:"inputs,omitempty" toml:"inputs,omitempty"`

	InputMapping map[string]string `json:"input_mapping,omitempty" toml:"input_mapping,omitempty"`

	NetworkParticipation *participation.Request `json:"network_participation,omitempty" toml:"network_participation,omitempty"`
}

LoopTarget configures an automation fire to start a Loop instead of an agent session.

func (*LoopTarget) Validate

func (t *LoopTarget) Validate(path string, scope Scope, automationWorkspaceID string) error

Validate ensures the loop target satisfies automation scope and basic payload shape.

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"`
	ProfileID            string                 `json:"profile_id,omitempty"`
	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"`
	LoopRunID            string                 `json:"loop_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"`
	NetworkParticipation *participation.Request `json:"network_participation,omitempty"`
	Metadata             map[string]any         `json:"metadata,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 {
	ReadScope store.ReadScope `json:"read_scope"`
	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 RunReservation

type RunReservation struct {
	Run             Run
	ExistingRunID   string
	ExpectedStatus  RunStatus
	ExpectedAttempt int
	Since           time.Time
	Until           time.Time
	Window          time.Duration
	Limit           int
	CountedStatuses []RunStatus
}

RunReservation atomically evaluates one rolling fire-limit window and, when capacity remains, reserves the supplied run. ExistingRunID identifies a run already created by the scheduler; that row is excluded from the window and verified instead of inserted again.

type RunReservationResult

type RunReservationResult struct {
	Run      Run
	Reserved bool
	Count    int64
	RetryAt  time.Time
}

RunReservationResult reports the durable fire-limit decision. Count is the number of matching runs observed before any new run was inserted.

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"`
	CatchUpPolicy       SchedulerCatchUpPolicy `json:"catch_up_policy,omitempty"       toml:"catch_up_policy,omitempty"`
	MisfireGraceSeconds int                    `json:"misfire_grace_seconds,omitempty" toml:"misfire_grace_seconds,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 dispatches the latest missed fire within
	// grace and otherwise advances after recording a durable skip.
	SchedulerCatchUpPolicySkipMissed SchedulerCatchUpPolicy = "skip_missed"
	// SchedulerCatchUpPolicyCoalesce dispatches one fire for the most recent missed instant.
	SchedulerCatchUpPolicyCoalesce SchedulerCatchUpPolicy = "coalesce"
	// SchedulerCatchUpPolicyReplay dispatches missed instants chronologically.
	SchedulerCatchUpPolicyReplay SchedulerCatchUpPolicy = "replay"
	// SchedulerCatchUpPolicyRunOnce dispatches only the latest missed instant.
	SchedulerCatchUpPolicyRunOnce SchedulerCatchUpPolicy = "run_once_on_catchup"
)

func (SchedulerCatchUpPolicy) Validate

func (p SchedulerCatchUpPolicy) Validate(path string) error

Validate ensures the scheduler catch-up policy is supported.

type SchedulerClaim

type SchedulerClaim struct {
	ProfileID            string
	JobID                string
	RunID                string
	FireID               string
	ScheduledAt          time.Time
	NextRunAt            *time.Time
	ClaimedAt            time.Time
	ScheduleHash         string
	CatchUpPolicy        SchedulerCatchUpPolicy
	MisfireGraceSeconds  int
	CatchUp              bool
	Misfire              bool
	SkipReason           SchedulerSkipReason
	NetworkParticipation *participation.Request
}

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
	Skipped    bool
	SkipReason SchedulerSkipReason
}

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

type SchedulerSkipReason

type SchedulerSkipReason string

SchedulerSkipReason identifies why a scheduled fire advanced without dispatch.

const (
	// SchedulerSkipReasonGraceExceeded reports a missed fire outside its grace window.
	SchedulerSkipReasonGraceExceeded SchedulerSkipReason = "misfire_grace_exceeded"
	// SchedulerSkipReasonSelfOverlap reports that the same job still has an active prior run.
	SchedulerSkipReasonSelfOverlap SchedulerSkipReason = "self_overlap"
	// SchedulerSkipReasonMetadataKey is the automation-run metadata key for durable skip evidence.
	SchedulerSkipReasonMetadataKey = "reason"
)

func (SchedulerSkipReason) Validate

func (r SchedulerSkipReason) Validate(path string) error

Validate ensures the scheduler skip reason is supported.

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 Suggestion

type Suggestion struct {
	ID          string           `json:"id"`
	ProfileID   string           `json:"profile_id"`
	WorkspaceID string           `json:"workspace_id"`
	Source      SuggestionSource `json:"source"`
	DedupKey    string           `json:"dedup_key"`
	Status      SuggestionStatus `json:"status"`
	Payload     Job              `json:"payload"`
	CreatedAt   time.Time        `json:"created_at"`
	ResolvedAt  *time.Time       `json:"resolved_at,omitempty"`
}

Suggestion is a profile-owned proposal for a prefilled Job. ProfileID binds the pending cap and payload to one profile. WorkspaceID is empty for global automation and otherwise binds the same proposal and payload to one workspace.

func (Suggestion) Validate

func (s Suggestion) Validate(path string) error

Validate ensures persisted suggestion metadata and resolution state are coherent.

type SuggestionSource

type SuggestionSource string

SuggestionSource identifies the emitter that proposed a Job.

const (
	// SuggestionSourceCatalog identifies the first-party starter catalog.
	SuggestionSourceCatalog SuggestionSource = "catalog"
	// SuggestionSourceUsage reserves usage-derived suggestions for a future emitter.
	SuggestionSourceUsage SuggestionSource = "usage"
	// SuggestionSourceIntegration reserves integration-derived suggestions for a future emitter.
	SuggestionSourceIntegration SuggestionSource = "integration"
)

func (SuggestionSource) Validate

func (s SuggestionSource) Validate(path string) error

Validate ensures the source belongs to the closed public enum.

type SuggestionStatus

type SuggestionStatus string

SuggestionStatus identifies the consent resolution state.

const (
	// SuggestionStatusPending has not received operator or agent consent.
	SuggestionStatusPending SuggestionStatus = "pending"
	// SuggestionStatusAccepted records durable consent to create the Job.
	SuggestionStatusAccepted SuggestionStatus = "accepted"
	// SuggestionStatusDismissed records durable refusal.
	SuggestionStatusDismissed SuggestionStatus = "dismissed"
)

func (SuggestionStatus) Validate

func (s SuggestionStatus) Validate(path string) error

Validate ensures the status belongs to the closed public enum.

type TargetKind

type TargetKind string

TargetKind identifies which runtime primitive an automation delegates to.

const (
	// TargetKindAgent starts the existing agent-session automation path.
	TargetKindAgent TargetKind = "agent"
	// TargetKindLoop starts a declared Loop through loop.Service.Start.
	TargetKindLoop TargetKind = "loop"
)

func (TargetKind) Normalize

func (k TargetKind) Normalize() TargetKind

Normalize trims the target kind.

func (TargetKind) Validate

func (k TargetKind) Validate(path string) error

Validate ensures the target kind is supported.

type Trigger

type Trigger struct {
	ID               string            `json:"id"`
	ProfileID        string            `json:"profile_id"`
	Scope            Scope             `json:"scope"`
	Name             string            `json:"name"`
	TargetKind       TargetKind        `json:"target_kind"`
	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"`
	LoopTarget       *LoopTarget       `json:"loop_target,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) IsLoopTarget

func (t Trigger) IsLoopTarget() bool

IsLoopTarget reports whether the trigger delegates to a Loop.

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 TriggerListPage

type TriggerListPage struct {
	Triggers   []Trigger `json:"triggers"`
	Total      int       `json:"total"`
	Limit      int       `json:"limit"`
	HasMore    bool      `json:"has_more"`
	NextCursor string    `json:"next_cursor,omitempty"`
}

TriggerListPage is one stable page of automation triggers.

func BuildTriggerListPage

func BuildTriggerListPage(triggers []Trigger, query TriggerListQuery) (TriggerListPage, error)

BuildTriggerListPage applies canonical trigger filters, ordering, and cursor pagination.

type TriggerListQuery

type TriggerListQuery struct {
	ReadScope   store.ReadScope `json:"read_scope"`
	Scope       Scope           `json:"scope,omitempty"`
	WorkspaceID string          `json:"workspace_id,omitempty"`
	Event       string          `json:"event,omitempty"`
	Source      JobSource       `json:"source,omitempty"`
	LoopName    string          `json:"loop_name,omitempty"`
	Enabled     *bool           `json:"enabled,omitempty"`
	Search      string          `json:"q,omitempty"`
	Cursor      string          `json:"cursor,omitempty"`
	Limit       int             `json:"limit,omitempty"`
}

TriggerListQuery filters persisted automation trigger listings.

func TriggerListQueryWithDefaultLimit

func TriggerListQueryWithDefaultLimit(query TriggerListQuery) TriggerListQuery

TriggerListQueryWithDefaultLimit normalizes a public trigger query and applies the default page size.

Jump to

Keyboard shortcuts

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