task

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jan 20, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CleanupStaleTasks 

func CleanupStaleTasks()

CleanupStaleTasks clears stale supervisor PIDs and records an error. Should be called before any workspace-acquiring operation.

func ConfigPath 

func ConfigPath() string

ConfigPath returns .subtask/config.json.

func CountProgressSteps 

func CountProgressSteps(steps []ProgressStep) (done, total int)

CountProgressSteps returns (done,total) for a set of steps.

func Dir 

func Dir(name string) string

Dir returns .subtask/tasks/<escaped-name>.

func EnsureOwnProcessGroup 

func EnsureOwnProcessGroup()

EnsureOwnProcessGroup puts the current process into its own process group (PGID == PID) so that interrupts can safely target the group without affecting unrelated processes.

Best-effort: if it fails, callers should fall back to PID-only signaling.

func EscapeName 

func EscapeName(name string) string

EscapeName converts "fix/epoch-boundary" to "fix--epoch-boundary".

func EscapePath 

func EscapePath(p string) string

EscapePath converts a path to a safe directory name. It resolves symlinks first to ensure consistency across different cwd resolutions.

func GlobalDir 

func GlobalDir() string

GlobalDir returns ~/.subtask.

func HistoryPath 

func HistoryPath(name string) string

HistoryPath returns the history.jsonl path.

func InternalDir 

func InternalDir() string

InternalDir returns .subtask/internal.

func List 

func List() ([]string, error)

List returns all task names in .subtask/tasks/.

func Path 

func Path(name string) string

Path returns the TASK.md path.

func ProjectDir 

func ProjectDir() string

ProjectDir returns .subtask in current dir.

func ProjectDirAbs 

func ProjectDirAbs() string

ProjectDirAbs returns the absolute path to the project's .subtask directory. If no .subtask directory exists in the cwd or any parent, it returns "<cwd>/.subtask".

func ProjectRoot 

func ProjectRoot() string

ProjectRoot returns the absolute path to the project root (the parent of .subtask). If no .subtask directory exists in the cwd or any parent, it returns the current working directory.

func SelfProcessGroupID 

func SelfProcessGroupID() int

SelfProcessGroupID returns the current process group ID, or 0 if unknown.

func StatePath 

func StatePath(name string) string

StatePath returns the state.json path.

func TasksDir 

func TasksDir() string

TasksDir returns .subtask/tasks.

func TryWithLock 

func TryWithLock(taskName string, fn func() error) (bool, error)

TryWithLock attempts to acquire an exclusive per-task lock without blocking. If the lock is already held by another process, it returns (false, nil).

func UnescapeName 

func UnescapeName(escaped string) string

UnescapeName converts "fix--epoch-boundary" to "fix/epoch-boundary".

func WithLock 

func WithLock(taskName string, fn func() error) error

WithLock acquires an exclusive per-task lock and runs fn while holding it.

func WorkspacesDir 

func WorkspacesDir() string

WorkspacesDir returns ~/.subtask/workspaces.

Types

type ConversationEvent 

type ConversationEvent struct {
	Type string
	Text string
	Time time.Time
}

ConversationEvent represents a lifecycle event (task opened, stage changed, etc.).

type ConversationHeader 

type ConversationHeader struct {
	Harness string
	Session string
}

ConversationHeader is derived metadata about a task's activity history. It is populated from history events (e.g. worker.session).

type ConversationItem 

type ConversationItem struct {
	IsEvent bool
	Message ConversationMessage
	Event   ConversationEvent
}

ConversationItem represents either a message or a lifecycle event in the timeline.

type ConversationMessage 

type ConversationMessage struct {
	Role ConversationRole
	Body string
	Time time.Time
}

type ConversationRole 

type ConversationRole string
const (
	ConversationRoleLead   ConversationRole = "lead"
	ConversationRoleWorker ConversationRole = "worker"
)

type Progress 

type Progress struct {
	ToolCalls  int       `json:"tool_calls,omitempty"`
	LastActive time.Time `json:"last_activity,omitempty"`
}

Progress is frequently-updated, informational task metadata. It is intentionally separated from State to avoid clobbering state transitions.

func LoadProgress 

func LoadProgress(taskName string) (*Progress, error)

LoadProgress reads progress from .subtask/internal/<task>/progress.json.

func (*Progress) Save 

func (p *Progress) Save(taskName string) error

Save writes progress to .subtask/internal/<task>/progress.json.

type ProgressStep 

type ProgressStep struct {
	Step string `json:"step"`
	Done bool   `json:"done"`
}

ProgressStep represents a step in PROGRESS.json (task folder).

func LoadProgressSteps 

func LoadProgressSteps(taskName string) []ProgressStep

LoadProgressSteps reads .subtask/tasks/<task>/PROGRESS.json.

This is best-effort and returns nil on missing/invalid files, matching the CLI's historical behavior (progress is informational).

type State 

type State struct {
	Workspace      string    `json:"workspace,omitempty"`       // absolute local path
	SessionID      string    `json:"session_id,omitempty"`      // current session
	Harness        string    `json:"harness,omitempty"`         // current session harness
	SupervisorPID  int       `json:"supervisor_pid,omitempty"`  // current run supervisor PID
	SupervisorPGID int       `json:"supervisor_pgid,omitempty"` // current run supervisor process group ID (unix)
	StartedAt      time.Time `json:"started_at,omitempty"`      // current run start (UTC)
	LastError      string    `json:"last_error,omitempty"`      // current/last run error
}

State is local, runtime-only state for a task.

This file is intentionally NOT syncable: it contains machine-specific details (workspace path) and ephemeral execution state (PIDs).

func LoadState 

func LoadState(taskName string) (*State, error)

LoadState reads state from .subtask/internal/<task>/state.json.

func (*State) IsStale 

func (s *State) IsStale() bool

IsStale returns true if a supervisor PID is recorded but the process is dead.

func (*State) Save 

func (s *State) Save(taskName string) error

Save writes the state to .subtask/internal/<task>/state.json. Uses fsync to ensure visibility to other processes (important for workspace locking).

type Task 

type Task struct {
	Name        string // Task name (e.g., "fix/epoch-boundary")
	Title       string // Short description
	BaseBranch  string // Branch to fork from
	FollowUp    string // Optional: task whose conversation to continue
	Model       string // Optional: override model for this task
	Reasoning   string // Optional: override reasoning (codex-only) for this task
	Schema      int    // Task schema version (0 if missing)
	Description string // Optional task description/context (not the prompt)
}

Task represents a task definition from TASK.md.

func Load 

func Load(name string) (*Task, error)

Load reads a task from .subtask/tasks/<name>/TASK.md.

func (*Task) Path 

func (t *Task) Path() string

Path returns the TASK.md path for this task.

func (*Task) Save 

func (t *Task) Save() error

Save writes the task to .subtask/tasks/<name>/TASK.md.

type TaskStatus 

type TaskStatus string

TaskStatus is the durable, syncable status of a task (stored in history.jsonl). 

const (
	TaskStatusOpen   TaskStatus = "open"
	TaskStatusMerged TaskStatus = "merged"
	TaskStatusClosed TaskStatus = "closed"
)

type UserStatus 

type UserStatus string

UserStatus is the simplified status shown to users (derived from task+worker state). 

const (
	UserStatusDraft   UserStatus = "draft" // open, worker never started
	UserStatusRunning UserStatus = "working"
	UserStatusReplied UserStatus = "replied"
	UserStatusError   UserStatus = "error"
	UserStatusMerged  UserStatus = "merged"
	UserStatusClosed  UserStatus = "closed"
)

func UserStatusFor 

func UserStatusFor(ts TaskStatus, ws WorkerStatus) UserStatus

UserStatusFor derives the user-visible status from the internal task+worker state.

type WorkerStatus 

type WorkerStatus string

WorkerStatus is the ephemeral status of the local worker process. 

const (
	// WorkerStatusNotStarted means the worker has never been invoked for this task yet.
	// This is represented as the empty string so it can be omitted easily in UIs.
	WorkerStatusNotStarted WorkerStatus = ""

	// WorkerStatusRunning means the worker is currently executing.
	//
	// Note: this used to be serialized as "running". We now use "working" but
	// accept both on read for backwards compatibility.
	WorkerStatusRunning WorkerStatus = "working"
	WorkerStatusReplied WorkerStatus = "replied"
	WorkerStatusError   WorkerStatus = "error"
)

func NormalizeWorkerStatus 

func NormalizeWorkerStatus(ws WorkerStatus) WorkerStatus

NormalizeWorkerStatus maps legacy serialized values to their current equivalents.

func ParseWorkerStatus 

func ParseWorkerStatus(s string) WorkerStatus

Source Files

View all Source files

Directories

Path Synopsis

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.