Documentation
¶
Overview ¶
Package automation exposes the automation workflow primitives for use by external embedders, seshat-ai, and cmd/automation workflows.
Index ¶
- Constants
- type AgentConfig
- type CronSchedule
- type DBJobStore
- type DiscardSink
- type ExecuteConfig
- type ExecuteFunc
- type ExecutionState
- type Executor
- type ExecutorConfig
- type FileSink
- type FileStateStore
- type IntervalSchedule
- type Job
- type JobRun
- type JobScheduler
- type JobStatus
- type JobStore
- type MemoryStateStore
- type Middleware
- type ModelIdentifier
- type MultiSink
- type OnceSchedule
- type Options
- type Registry
- type Result
- type RunStatus
- type Runner
- type RunnerConfig
- type Schedule
- type ScheduledRun
- type Scheduler
- type Sink
- type StateStore
- type StdoutSink
- type SystemPrompter
- type Trigger
- type TriggerType
- type WebhookSink
- type Workflow
Constants ¶
const ( TriggerTypeCron = automation.TriggerTypeCron TriggerTypeInterval = automation.TriggerTypeInterval TriggerTypeOnce = automation.TriggerTypeOnce TriggerTypeEvent = automation.TriggerTypeEvent JobStatusActive = automation.JobStatusActive JobStatusPaused = automation.JobStatusPaused JobStatusInactive = automation.JobStatusInactive RunStatusRunning = automation.RunStatusRunning RunStatusSuccess = automation.RunStatusSuccess RunStatusError = automation.RunStatusError )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AgentConfig ¶
type AgentConfig = automation.AgentConfig
AgentConfig defines the agent that executes a job. When Slug is set the daemon resolves the full agent definition from seshat-ai and uses it as the base configuration; all other fields act as overrides.
type CronSchedule ¶
type CronSchedule = automation.CronSchedule
CronSchedule fires according to a standard 5-field cron expression:
┌───────────── minute (0–59) │ ┌─────────── hour (0–23) │ │ ┌───────── dom (1–31) │ │ │ ┌─────── month (1–12) │ │ │ │ ┌───── weekday (0–6, 0=Sun) │ │ │ │ │ * * * * *
Supports: *, N, N-M, */N, N,M,…, and combinations thereof. When both dom and dow are restricted (neither is *), POSIX cron semantics fire on EITHER matching (not both) - e.g. "0 9 15 * 1" fires at 9am on the 15th of every month AND every Monday, not only when the 15th is a Monday. Parsing/computation is delegated to robfig/cron (MIT), which already implements this correctly - a hand-rolled bitmask parser used to live here and got the dom/dow OR-semantics wrong (AND instead of OR). Idea to use a battle-tested cron library instead of a hand-rolled parser came from studying neul-labs/m9m (MIT), which does the same.
func Cron ¶
func Cron(expr string) (*CronSchedule, error)
Cron parses a 5-field cron expression. Returns an error on invalid syntax.
type DBJobStore ¶
type DBJobStore = automation.DBJobStore
DBJobStore implements JobStore backed by a seshat DB instance.
type DiscardSink ¶
type DiscardSink = automation.DiscardSink
DiscardSink silently drops every result. Useful in tests.
type ExecuteConfig ¶
type ExecuteConfig = automation.ExecuteConfig
ExecuteConfig holds per-execution overrides applied on top of RunnerConfig.
type ExecuteFunc ¶
type ExecuteFunc = automation.ExecuteFunc
ExecuteFunc is the core execution signature threaded through the middleware chain.
type ExecutionState ¶
type ExecutionState = automation.ExecutionState
ExecutionState tracks the persistent history of a workflow across runs.
type Executor ¶
type Executor = automation.Executor
Executor orchestrates workflow execution: it combines the Runner with middleware, output sinks, and state management.
func NewExecutor ¶
func NewExecutor(cfg ExecutorConfig) (*Executor, error)
NewExecutor builds an Executor from cfg. WithRecovery() is always prepended so panics never escape.
type ExecutorConfig ¶
type ExecutorConfig = automation.ExecutorConfig
ExecutorConfig configures the Executor.
type FileSink ¶
type FileSink = automation.FileSink
FileSink writes the result to a file. The filename is derived from the workflow name and the run timestamp.
type FileStateStore ¶
type FileStateStore = automation.FileStateStore
FileStateStore persists one JSON file per workflow in a directory. It is safe for use by a single process (no cross-process locking).
func NewFileStateStore ¶
func NewFileStateStore(dir string) (*FileStateStore, error)
NewFileStateStore creates a state store that keeps one JSON file per workflow in dir, creating the directory if needed, so the states survive a restart.
type IntervalSchedule ¶
type IntervalSchedule = automation.IntervalSchedule
IntervalSchedule fires every fixed Interval starting from first use.
func Every ¶
func Every(d time.Duration) *IntervalSchedule
Every returns a schedule that fires at a fixed interval d after the previous run.
type Job ¶
type Job = automation.Job
Job is a persisted automation task: trigger + agent config + task description.
type JobScheduler ¶
type JobScheduler = automation.JobScheduler
JobScheduler manages the lifecycle of persisted automation jobs. It ticks every 10 seconds, checks due jobs, and fires them as goroutines. All job state is persisted via JobStore so the scheduler survives restarts.
func NewJobScheduler ¶
func NewJobScheduler(store JobStore, runner *Runner) *JobScheduler
NewJobScheduler builds a JobScheduler backed by store and runner. To create a DBJobStore, use internal/automation.NewDBJobStore with a *db.DB.
type JobStatus ¶
type JobStatus = automation.JobStatus
JobStatus is the state of a job: active, paused, or inactive (a once-trigger that already fired).
type JobStore ¶
type JobStore = automation.JobStore
JobStore is the persistence interface for automation jobs and their runs.
type MemoryStateStore ¶
type MemoryStateStore = automation.MemoryStateStore
MemoryStateStore is an in-process store with no persistence. Suitable for testing or ephemeral single-run scenarios.
func NewMemoryStateStore ¶
func NewMemoryStateStore() *MemoryStateStore
NewMemoryStateStore creates a state store held in memory: the states are lost when the process ends.
type Middleware ¶
type Middleware = automation.Middleware
Middleware wraps an ExecuteFunc to add cross-cutting behaviour. Middlewares are applied innermost-first: Chain(A, B, C) produces A(B(C(core))).
func Chain ¶
func Chain(mw ...Middleware) Middleware
Chain composes a slice of middlewares into a single middleware. The first middleware is the outermost (runs first on entry, last on exit).
func WithLogging ¶
func WithLogging(l *log.Logger) Middleware
WithLogging logs workflow start, completion, and errors to logger. Pass nil to use the default log package.
func WithMetrics ¶
func WithMetrics(fn func(Result)) Middleware
WithMetrics calls onResult after every execution (success or failure). Use this to feed Prometheus counters, Datadog metrics, or custom logging.
func WithRecovery ¶
func WithRecovery() Middleware
WithRecovery catches panics from the workflow, converts them to errors, and ensures the Result is always populated.
func WithRetry ¶
func WithRetry(n int, b time.Duration) Middleware
WithRetry retries a failed workflow up to maxAttempts additional times, waiting backoff (doubled each attempt) between attempts. Overrides opts.MaxRetries and opts.RetryBackoff when both are non-zero.
func WithTimeout ¶
func WithTimeout(d time.Duration) Middleware
WithTimeout cancels the workflow if it exceeds d. Opts.Timeout takes precedence when non-zero.
type ModelIdentifier ¶
type ModelIdentifier = sdk.ModelIdentifier
ModelIdentifier uniquely identifies a model: a provider and a model name.
type MultiSink ¶
type MultiSink = automation.MultiSink
MultiSink fans a Result out to multiple sinks. All sinks are called even if one errors; errors are joined.
func NewMultiSink ¶
NewMultiSink creates a sink that writes each result to every one of sinks. A failure of one does not stop the others; the errors are returned together.
type OnceSchedule ¶
type OnceSchedule = automation.OnceSchedule
OnceSchedule fires exactly once at At.
func Once ¶
func Once(at time.Time) *OnceSchedule
Once returns a schedule that fires a single time, at the given instant. A time that has already passed never fires.
type Options ¶
type Options = automation.Options
Options configure a single workflow execution. Workflow-specific parameters (e.g. topics, target path) belong in the workflow struct itself; Options covers cross-cutting execution concerns.
func DefaultOptions ¶
func DefaultOptions() Options
DefaultOptions returns sensible defaults for interactive or scheduled runs.
type Registry ¶
type Registry = automation.Registry
Registry is a thread-safe catalog of named workflows. Workflows are registered once at startup and looked up by name at runtime.
type Result ¶
type Result = automation.Result
Result holds the complete outcome of a single workflow execution.
type RunStatus ¶
type RunStatus = automation.RunStatus
RunStatus is the state of one execution of a job: running, success or error.
type Runner ¶
type Runner = automation.Runner
Runner creates a fresh SDK client for each workflow execution. It holds no mutable state, making it safe for concurrent use.
func NewRunner ¶
func NewRunner(cfg RunnerConfig) (*Runner, error)
NewRunner builds a Runner from cfg.
type RunnerConfig ¶
type RunnerConfig = automation.RunnerConfig
RunnerConfig is the base template used to build an SDK client for each workflow execution.
func RunnerConfigFromEnv ¶
func RunnerConfigFromEnv(modelRaw string) (RunnerConfig, error)
RunnerConfigFromEnv resolves provider credentials from the environment and seshat config file. modelRaw follows "provider:model" format.
type Schedule ¶
type Schedule = automation.Schedule
Schedule computes the next trigger time after a given reference point.
type ScheduledRun ¶
type ScheduledRun = automation.ScheduledRun
ScheduledRun is a read-only view of a single job's next execution.
type Scheduler ¶
type Scheduler = automation.Scheduler
Scheduler runs registered workflows according to their schedules. It uses a single goroutine and a timer-based loop; it does not spawn a goroutine per job. Concurrent job execution is not supported by design — use multiple Schedulers if you need parallel pipelines.
func NewScheduler ¶
NewScheduler creates a Scheduler backed by executor.
type Sink ¶
type Sink = automation.Sink
Sink receives a completed Result after a workflow finishes. Sinks are called sequentially by the Executor; use MultiSink for fan-out.
type StateStore ¶
type StateStore = automation.StateStore
StateStore persists and retrieves execution state across process restarts.
type StdoutSink ¶
type StdoutSink = automation.StdoutSink
StdoutSink prints a human-readable summary of the result to stdout. The workflow's streaming output is already printed in real time via StreamFn; StdoutSink adds a completion footer (duration, status).
type SystemPrompter ¶
type SystemPrompter = automation.SystemPrompter
SystemPrompter is an optional interface a Workflow can implement to provide a fully custom system prompt that replaces the Seshat default. When satisfied, the Executor builds a dedicated SDK client for that execution.
type TriggerType ¶
type TriggerType = automation.TriggerType
TriggerType is how a job is triggered: cron, interval, once, or event (on demand, dispatched by the application, with no schedule).
type WebhookSink ¶
type WebhookSink = automation.WebhookSink
WebhookSink sends the result as a JSON POST to a URL.
func NewWebhookSink ¶
func NewWebhookSink(url string) *WebhookSink
NewWebhookSink creates a sink that posts each result as JSON (workflow name, start and end times, duration, success, output, metadata and error) to url, with a timeout of 15 seconds.
type Workflow ¶
type Workflow = automation.Workflow
Workflow is the interface every automation workflow must implement.
Source Files