Documentation
¶
Overview ¶
Package tasks — cross-session task graph (§8.3 Phase 5 #2).
The agent tracks user requests that span sessions: "fix the auth bug" from Tuesday, "add CSRF protection" from yesterday. Each request becomes a Task with a status (open / shipped / abandoned) and a list of linked commits. At session open the agent reads the open threads and surfaces them — "you asked me to fix X 3 days ago, that shipped (abc123)".
Storage: one JSON file per task at ~/.overkill/tasks/<id>.json. Atomic temp+rename so a crash mid-write leaves the prior state intact. Single-file-per-task is simpler than JSONL when we need to mutate status / link commits — no fold-from-zero on every read.
Linking: tasks are linked to commits via two paths:
- Trailer match: the agent inserts `Overkill-Task: <id>` in commit messages. The boot scan reads `git log --grep` for the trailer.
- Keyword scan: the agent can call LinkCommit explicitly with a known SHA when it recognizes the work that just shipped.
Either path is best-effort. The git surface lives outside this package — keeps internal/tasks portable + testable without git.
Index ¶
- func FormatOpenerSummary(open []*Task) string
- type Status
- type Store
- func (s *Store) All() ([]*Task, error)
- func (s *Store) AppendNote(id, note string) (*Task, error)
- func (s *Store) Delete(id string) error
- func (s *Store) ExportJSONL(w *bufio.Writer) error
- func (s *Store) Get(id string) (*Task, error)
- func (s *Store) LinkCommit(id, sha string) (*Task, error)
- func (s *Store) Open(sessionID, intent string) (*Task, error)
- func (s *Store) OpenOlderThan(age time.Duration) ([]*Task, error)
- func (s *Store) OpenTasks() ([]*Task, error)
- func (s *Store) Search(query string) ([]*Task, error)
- func (s *Store) SetStatus(id string, status Status) (*Task, error)
- func (s *Store) UpdateIntent(id, sessionID, intent string) (*Task, error)
- type Task
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FormatOpenerSummary ¶
FormatOpenerSummary renders the boot-time message the agent surfaces when there are stale open tasks. Empty when nothing qualifies. Caller decides the age threshold via OpenOlderThan.
Types ¶
type Status ¶
type Status string
Status is the current lifecycle position of a Task.
const ( // StatusOpen: user asked, agent hasn't shipped yet. StatusOpen Status = "open" // StatusInProgress: agent is actively working on it. StatusInProgress Status = "in_progress" // StatusShipped: agent considers it done. Commits attached. StatusShipped Status = "shipped" // StatusAbandoned: user / agent decided not to do it. StatusAbandoned Status = "abandoned" )
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store wraps the on-disk tasks directory.
func (*Store) AppendNote ¶
AppendNote attaches a one-line update to the task's Notes field. Multiple notes are separated by " | " so the field stays a single JSON string (no schema churn). Returns an error for empty input (B116).
func (*Store) Delete ¶
Delete removes a task file by ID. No-op when the task doesn't exist (idempotent — delete what isn't there is still success).
func (*Store) ExportJSONL ¶
ExportJSONL writes every persisted task as one JSONL line per task to w. Used by sync / backup. Newest-first.
func (*Store) LinkCommit ¶
LinkCommit attaches a commit SHA to the task. Idempotent — re-linking the same SHA is a no-op. Does NOT auto-transition to shipped; the caller decides whether one linked commit is enough.
func (*Store) Open ¶
Open creates a new task in StatusOpen. Returns the task with its assigned ID. Empty intent is rejected (a task without a distilled intent isn't useful).
func (*Store) OpenOlderThan ¶
OpenOlderThan returns non-terminal tasks created more than `age` ago. The session-open surface uses this to filter out things the user just asked about (no point reminding them about a request from 5 minutes ago).
func (*Store) OpenTasks ¶
Open returns tasks in StatusOpen or StatusInProgress, newest-first. Used at session open to surface unfinished threads.
func (*Store) Search ¶
Search substring-matches across Intent / Notes / Tags case-insensitively. Empty query returns empty.
type Task ¶
type Task struct {
ID string `json:"id"`
SessionID string `json:"session_id"`
Intent string `json:"intent"`
Status Status `json:"status"`
Commits []string `json:"commits,omitempty"`
Tags []string `json:"tags,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
ResolvedAt time.Time `json:"resolved_at,omitempty"`
// Notes is free-form prose the agent attaches mid-flight:
// "tried X, it failed because Y; switching to Z". Useful for
// the session-open surface even before commits land.
Notes string `json:"notes,omitempty"`
}
Task is one cross-session task record.
func (*Task) IsTerminal ¶
IsTerminal reports whether the task is in a final state.
Source Files