Documentation
¶
Overview ¶
Package routine implements named, managed headless agent runs.
A routine is a directory under ~/.config/task/routines/<name>/ containing a prompt.md (the agent prompt, with optional frontmatter for model/project/ timeout) and an optional env.sh sourced before each run for secrets and fail-fast checks. Routines have no scheduler: anything — launchd, cron, a shell — triggers a run with `ty run <name>`. TaskYou owns the run itself: state, logs, history, and failure alerting.
Index ¶
- Constants
- func Delete(name string) error
- func Exists(name string) bool
- func LoadSchedules(names []string) (map[string]*Schedule, error)
- func RemoveSchedule(name string) (bool, error)
- func RenderSchedule(name string, opts ScheduleOptions) (backend, content string, err error)
- func RoutinesDir() string
- func StateDir(name string) string
- func ValidateName(name string) error
- type Routine
- type RunResult
- type Runner
- type Schedule
- type ScheduleOptions
Constants ¶
const ( // DefaultModel keeps unattended runs on a cheap model unless the routine // explicitly opts into a bigger one. DefaultModel = "sonnet" // DefaultTimeout bounds a hung headless run so an unattended scheduler // invocation can't wedge forever. DefaultTimeout = 30 * time.Minute )
Variables ¶
This section is empty.
Functions ¶
func Delete ¶
Delete removes the routine's definition directory and its state directory (including logs). Run history in the database is the caller's to prune via db.DeleteRoutineRuns.
func LoadSchedules ¶
LoadSchedules resolves live schedules for many routines with one pass over the LaunchAgents dir and one crontab read (the TUI and list call this).
func RemoveSchedule ¶
RemoveSchedule removes any ty-managed scheduler entry for the routine. Idempotent: removing a routine that isn't scheduled returns (false, nil).
func RenderSchedule ¶
func RenderSchedule(name string, opts ScheduleOptions) (backend, content string, err error)
RenderSchedule returns the scheduler config that InstallSchedule would install, for --print and for tests.
func RoutinesDir ¶
func RoutinesDir() string
RoutinesDir returns the directory routine definitions live in.
func StateDir ¶
StateDir returns the per-routine state directory. It is exported to the agent as ROUTINE_STATE_DIR and used as the run's working directory, so routines keep cross-run state (seen IDs, cursors) without inventing paths.
func ValidateName ¶
ValidateName rejects names that aren't safe as path components.
Types ¶
type Routine ¶
type Routine struct {
Name string
Dir string // ~/.config/task/routines/<name>
Prompt string // prompt.md body with frontmatter stripped
Model string // claude model (frontmatter "model", default sonnet)
Project string // project for emitted/alert tasks (frontmatter "project")
PermissionMode string // frontmatter "permission-mode", default dangerous (headless runs can't answer prompts)
Timeout time.Duration // frontmatter "timeout" (Go duration), default 30m
WorkDir string // frontmatter "dir": run cwd override (for repo context / project-scoped MCP); default = state dir
Disabled bool // presence of a "disabled" file in Dir
}
Routine is a loaded routine definition.
func List ¶
List loads every routine under RoutinesDir, sorted by name. Directories without a prompt.md are skipped; unparseable routines are returned as an error so a typo doesn't silently hide a routine from the list.
func (*Routine) SetDisabled ¶
SetDisabled creates or removes the routine's disabled marker file.
type RunResult ¶
type RunResult struct {
RunID int64
Status string
ExitCode int
Output string
LogPath string
Duration time.Duration
}
RunResult describes a finished routine run.
type Runner ¶
type Runner struct {
DB *db.DB
Emitter *events.Emitter
// ClaudeBin overrides the agent binary (tests use a stub). Empty = "claude".
ClaudeBin string
// Stdout, when set, receives a live copy of the run output (in addition to
// the log file) so `ty run` invoked by hand shows progress.
Stdout io.Writer
}
Runner executes routines and records their runs.
type Schedule ¶
type Schedule struct {
Backend string // "launchd" or "cron"
Detail string // human summary, e.g. "every 30m" or "0 8 * * *"
Path string // plist path (launchd) or "crontab" (cron)
}
Schedule describes a live OS-scheduler entry for a routine.
func InstallSchedule ¶
func InstallSchedule(name string, opts ScheduleOptions) (*Schedule, error)
InstallSchedule registers the routine with the OS scheduler and returns the live Schedule. Re-installing replaces any previous ty-managed entry.
func ScheduledFor ¶
ScheduledFor returns the routine's live ty-managed schedule, or nil if none exists. It reads the OS scheduler directly — there is no cached state to disagree with reality.
type ScheduleOptions ¶
type ScheduleOptions struct {
Every time.Duration // interval cadence
Cron string // five-field cron expression
}
ScheduleOptions describes the requested cadence. Exactly one of Every or Cron must be set: intervals install a launchd agent on macOS (cron elsewhere), cron expressions always install a crontab line.
Source Files