Files
archie/internal/taskstate/taskstate.go
T
sam d320a1a01a feat(eda): workflow inputs, optional repository and agent profiles
Workflow definitions declare inputs, repository (none, optional or
required; default required) and profile. A binding assigns each input
from a mapped parameter or a constant and may take its repository from a
parameter, which must name a configured repo; both are checked when the
binding is saved and again at dispatch. Inputs travel as structured task
data (tasks.inputs, the task brief, and a JSON block in the agent's
mission), never as body text.

A task with no repository runs in a per-task scratch workspace with no
clone and no publication grant. The agent.run step runs one mission
without a repository and finishes the task in the new completed status.

Agent profiles live under [containers.profiles.<name>]: an image and an
allowlist over the tools archie adds (MCP, scripts, plugins).
[containers].image is the default profile; an unconfigured profile parks
the task. The workflow is now pinned before the container starts so the
profile can choose its image.

Also stop two archied tests writing embedded NATS state into the package
directory, refuse an empty state_dir for embedded NATS, and drop the NATS
store files an earlier lane commit tracked.
2026-09-24 20:29:33 +10:00

237 lines
9.3 KiB
Go

// Package taskstate owns the task lifecycle vocabulary and the rules for
// operator-initiated actions on a task.
//
// It exists because those rules had two implementations. The dashboard and
// chat both offer approve and reject, and they had drifted: rejecting from
// the dashboard left a task ClosedWontDo, cancelling the same task from chat
// left it Rejected. Two operators looking at the same queue saw different
// states for the same decision, and Rejected -- which the PR reconciler uses
// for "the pull request was closed without merging" -- no longer meant one
// thing.
//
// internal/gateway deliberately does not import the task store, so it kept a
// hand-synced copy of the status strings with a comment asking future editors
// to keep them aligned. That is the same defect one level down. This package
// has no dependencies, so both can import it and the copy can go.
package taskstate
import (
"fmt"
"slices"
)
// Action is an operator control whose availability is determined solely by a
// task's persisted lifecycle state. The Web API returns these values with each
// task so every presentation surface derives from this table instead of
// keeping its own copy.
type Action string
const (
ActionCancel Action = "cancel"
ActionStop Action = "stop"
ActionApprove Action = "approve"
ActionReject Action = "reject"
ActionRetry Action = "retry"
ActionAbandon Action = "abandon"
ActionOpenPR Action = "open_pr"
ActionOpenIssue Action = "open_issue"
ActionArchive Action = "archive"
)
// Task lifecycle statuses. The store persists these strings, so they are
// part of the on-disk format: renaming one is a migration, not a rename.
const (
Queued = "queued"
Running = "running"
WaitingHuman = "waiting_human"
PROpen = "pr_open"
Merged = "merged"
Parked = "parked"
Dead = "dead"
// Rejected means the forge closed the pull request without merging it.
// It is an outcome archie observed, not a decision an operator made --
// use Declined for that.
Rejected = "rejected"
// Declined means an operator refused the work. Whether they said so from
// the dashboard or from chat, the task lands here.
Declined = "closed_wont_do"
// Completed means a workflow that opens no pull request finished its
// work, such as a run with no repository.
Completed = "completed"
)
// Terminal reports whether a status is an end state, from which no further
// work happens without an operator asking for it.
func Terminal(status string) bool {
switch status {
case Merged, Rejected, Dead, Declined, Completed:
return true
default:
return false
}
}
// Actions returns the ordered controls valid for status. Callers receive a
// fresh slice so presentation code cannot mutate the lifecycle table.
//
// Reject is deliberately present in every non-terminal state: an operator can
// refuse work no matter where it currently sits, and the refusal always lands
// in the terminal Declined state. Terminal states are already resolved, so
// they only expose archive.
func Actions(status string) []Action {
var actions []Action
switch status {
case Queued:
actions = []Action{ActionCancel, ActionReject}
case Running:
actions = []Action{ActionStop, ActionReject}
case WaitingHuman:
actions = []Action{ActionApprove, ActionReject}
case Parked:
actions = []Action{ActionRetry, ActionAbandon, ActionReject}
case PROpen:
actions = []Action{ActionOpenPR, ActionOpenIssue, ActionReject}
case Merged, Rejected, Dead, Declined, Completed:
actions = []Action{ActionArchive}
}
return actions
}
// CheckAction rejects stale, illegal and unknown operator controls.
func CheckAction(status string, action Action) error {
if slices.Contains(Actions(status), action) {
return nil
}
return fmt.Errorf("action %q is not available while task is %s", action, status)
}
// CheckApprove reports whether a task in this status can be approved.
//
// Approval releases work that is waiting on a human decision, so it is only
// meaningful from WaitingHuman. Approving anything else would either restart
// finished work or race a task that is already running.
func CheckApprove(status string) error {
if status != WaitingHuman {
return fmt.Errorf("task is %s, not awaiting approval", status)
}
return nil
}
// CheckRetry reports whether a task in this status can be retried.
//
// Only a parked task can be retried: parking is how archie says "this failed
// in a way a human might fix". A dead task has spent its retries and needs
// the cap raised or the work re-filed, not another attempt.
func CheckRetry(status string) error {
if status != Parked {
return fmt.Errorf("task is %s, not parked", status)
}
return nil
}
// CheckDecline reports whether a task in this status can be declined.
//
// The legacy chat command expresses cancel, stop, reject and abandon as one
// operation. Because Reject is now offered in every non-terminal state, that
// command is available everywhere a task is still live; unknown and terminal
// states fail closed instead of permitting an arbitrary transition.
func CheckDecline(status string) error {
for _, action := range Actions(status) {
switch action {
case ActionCancel, ActionStop, ActionReject, ActionAbandon:
return nil
}
}
return fmt.Errorf("task cannot be declined while %s", status)
}
// StatusMeta describes how to present a lifecycle status. It is the single
// source for the dashboard's label, pill severity and "needs you" grouping, so
// the frontend never has to keep a hand-synced copy of the vocabulary.
type StatusMeta struct {
ID string `json:"id"`
Label string `json:"label"`
Kind string `json:"kind"` // pill severity: idle, info, ok, warn, danger
NeedsYou bool `json:"needs_you"` // counts toward the "Needs you" filter
}
// ActionMeta describes how to present an operator control. Confirmation text
// uses "{title}" as a placeholder for the task title.
type ActionMeta struct {
ID string `json:"id"`
Label string `json:"label"`
Kind string `json:"kind"` // button variant: primary, quiet, danger, link
Confirm string `json:"confirm"` // optional confirm prompt, may be ""
}
// Statuses returns the presentation catalog for every lifecycle status, in
// display order. Callers receive a fresh slice.
func Statuses() []StatusMeta {
return []StatusMeta{
{ID: Queued, Label: "Queued", Kind: "idle"},
{ID: Running, Label: "Working", Kind: "info"},
{ID: WaitingHuman, Label: "Waiting for you", Kind: "warn", NeedsYou: true},
{ID: PROpen, Label: "In review", Kind: "ok"},
{ID: Merged, Label: "Merged", Kind: "ok"},
{ID: Completed, Label: "Done", Kind: "ok"},
{ID: Parked, Label: "Parked", Kind: "warn", NeedsYou: true},
{ID: Dead, Label: "Stopped (too many retries)", Kind: "danger"},
{ID: Rejected, Label: "Rejected", Kind: "danger"},
{ID: Declined, Label: "Won't do", Kind: "idle"},
}
}
// ActionCatalog returns the presentation catalog for every operator control.
// Callers receive a fresh slice.
func ActionCatalog() []ActionMeta {
return []ActionMeta{
{ID: string(ActionCancel), Label: "Cancel", Kind: "quiet", Confirm: `Cancel "{title}"? This closes the forge issue.`},
{ID: string(ActionStop), Label: "Stop", Kind: "primary", Confirm: `Stop "{title}"? Recoverable work will remain parked.`},
{ID: string(ActionApprove), Label: "Approve", Kind: "primary"},
{ID: string(ActionReject), Label: "Reject", Kind: "quiet", Confirm: `Reject "{title}"? This closes the forge issue.`},
{ID: string(ActionRetry), Label: "Retry", Kind: "primary"},
{ID: string(ActionAbandon), Label: "Abandon", Kind: "quiet", Confirm: `Abandon "{title}"? This closes the forge issue.`},
{ID: string(ActionArchive), Label: "Archive", Kind: "quiet", Confirm: `Archive the local record for "{title}"?`},
{ID: string(ActionOpenPR), Label: "Open PR", Kind: "link"},
{ID: string(ActionOpenIssue), Label: "Open issue", Kind: "link"},
}
}
// Park classes: the producer-side answer to "what kind of intervention does
// this park need?" (docs/prds/pr-review-remediation.md's F2, the typed
// classification agent-system.md:327 acknowledges the data model lacks).
// The class is recorded at the park site, where the cause is known, and is
// never inferred later from reason text. It is part of the on-disk format.
const (
// ParkNeedsHuman parks need an operator decision: gate failures,
// review verdicts, diff caps, remediation round caps. It is the
// default, so an unclassified park always reads as operator-actionable.
ParkNeedsHuman ParkClass = "needs_human"
// ParkTransient parks are environmental: storage, container pool,
// grants, transport. Nothing about the work is wrong; a requeue can
// succeed. Nothing retries them automatically yet -- the class is
// recorded so a future retry pass has a safe, queryable input.
ParkTransient ParkClass = "transient"
// ParkTerminal parks cannot be retried into success: the repo left the
// config, the owning identity retired. An operator archives these.
ParkTerminal ParkClass = "terminal"
)
// ParkClass is the persisted park classification string.
type ParkClass = string
// NormalizeParkClass maps a park class written by a producer to the value
// the store persists. Empty and unknown fall back to NeedsHuman: the safe
// misread is "an operator should look at this", never "nothing to do".
func NormalizeParkClass(class string) ParkClass {
switch class {
case ParkTransient, ParkTerminal:
return class
default:
return ParkNeedsHuman
}
}