Files
archie/internal/domain/workflow/task/task.go
T
sam bea1c69210 feat(staterpc): carry the review gate and re-review rounds, with one guarded response write
The operator-approval gate needs its conversation with the operator
persisted before it waits and its answer threaded back
(docs/prds/pr-review-operator-response.md, Decision 2). review_gate is a
text column beside review_payload, encoded by the package that owns the
type; rereview_rounds is a bigint counted only by the new guarded write.

RespondReviewGate is the one write beside RetryTask/BeginRemediation: a
transition-table guard, one from-status check, an optional round
increment, and a requeue in one transaction. The re-review cap is
enforced in the row under the guard's lock, and a refusal leaves the
task waiting and the row untouched, surfaced as ErrRereviewCapReached
(added to the wire error table and the conformance battery). The column
joins the column-listing ListTaskSummaries projection and UpdateTask, so
the dashboard reads the offer and the store round-trips the count.
2026-10-02 02:27:59 +10:00

251 lines
12 KiB
Go

// Package task is the task-execution vocabulary of the workflow domain:
// the Task record, its lifecycle statuses, and the narrow Store contract
// workflow stages call mid-run. It split out of package workflow
// (archie-core-8cda.5.6) so the UI process can hold the vocabulary without
// linking the pipeline engine there -- which drags in agentexec, skill and
// tools. package workflow keeps aliases, so daemon-side callers are
// unaffected.
package task
import (
"context"
"encoding/json"
"time"
"github.com/samcharles93/archie-core/internal/domain/org"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/taskstate"
)
// Task lifecycle statuses. Workflows move tasks between them; the
// daemon owns queued→running claims and crash recovery.
const (
// Defined in internal/taskstate so the dashboard, chat and the store
// share one vocabulary. These names are kept as the workflow domain's
// public spelling; the values live in one place.
StatusQueued = taskstate.Queued
StatusRunning = taskstate.Running
StatusWaitingHuman = taskstate.WaitingHuman
StatusPROpen = taskstate.PROpen
StatusMerged = taskstate.Merged
StatusParked = taskstate.Parked
StatusDead = taskstate.Dead
StatusRejected = taskstate.Rejected
StatusClosedWontDo = taskstate.Declined
StatusCompleted = taskstate.Completed
)
// Task is the task-execution record the workflow domain operates on.
// internal/infrastructure/postgres persists this type (persistence -> domain).
type Task struct {
ID int64 `json:"id"`
Owner string `json:"owner"`
Repo string `json:"repo"`
IssueNumber int `json:"issue_number"`
Title string `json:"title"`
Body string `json:"body"`
Labels string `json:"labels"` // comma-separated, as seen at enqueue time
Status string `json:"status"`
Workflow string `json:"workflow"`
// WorkflowDefinitionVersion and WorkflowDefinitionDigest pin the exact
// database definition selected for this execution. WorkflowDefinitionYAML
// is the immutable worker handoff; retries reuse it instead of re-reading
// the active control-plane resource.
WorkflowDefinitionVersion int64 `json:"workflow_definition_version"`
WorkflowDefinitionDigest string `json:"workflow_definition_digest"`
WorkflowDefinitionYAML string `json:"workflow_definition_yaml"`
Branch string `json:"branch"`
Plan string `json:"plan"`
Notes string `json:"notes"`
PRNumber int `json:"pr_number"`
TokensUsed int `json:"tokens_used"`
Iterations int `json:"iterations"`
Attempt int `json:"attempt"`
ParkReason string `json:"park_reason"`
// RetryCount tracks how many times a parked task has been retried
// (parking-to-queued transitions). When it reaches the configured
// max_retries the daemon moves the task to StatusDead.
RetryCount int `json:"retry_count"`
// WatchCommentID is the poll backstop's high-water mark over forge
// review-comment IDs for this task (pr-review-remediation.md decision
// 2's persisted per-task cursor; the comment-watch design it was
// created for never shipped, and the field carries the cursor now).
WatchCommentID int64 `json:"watch_comment_id"`
// ReviewCursor is the poll backstop's high-water mark over forge
// review IDs. It is deliberately separate from WatchCommentID: review
// and comment IDs are independent forge sequences, and one combined
// cursor would silently skip reviews once a larger comment ID landed.
ReviewCursor int64 `json:"review_cursor"`
// Source is "forge" (default; a real forge issue backs this task) or
// "chat" (created via /spawn with no forge issue). Workflow stages
// and daemon reconciliation must skip forge-only operations (issue
// labels, comments, replies) for chat-sourced tasks; IssueNumber on
// a chat task is a synthetic value, not a real forge issue.
Source string `json:"source"`
// Identity is the archie identity that owns this task (chat-spawned
// tasks only; empty for forge-sourced tasks and single-identity
// deployments). Used to scope /approve and /cancel authorization so
// one identity cannot control another's chat-spawned tasks.
Identity string `json:"identity"`
// Org is the org the task belongs to. The State Store derives it from
// the task's identity when the row is written
// (docs/prds/orgs-and-access.md, "Events and task identity"); a task
// of a single-operator install belongs to the default org.
Org org.OrgID `json:"org,omitempty"`
// BindingID and BindingVersion are stamped when a task was created
// from a playbook binding dispatch (t2db.4 Phase B). They record
// provenance: which binding fired this task and at what version, so
// later edits to the binding cannot silently rewrite history.
BindingID string `json:"binding_id"`
BindingVersion int `json:"binding_version"`
// Inputs are the workflow inputs the binding assigned, checked against
// the workflow's declared inputs at dispatch. They reach the agent as
// structured data, never as body text.
Inputs map[string]any `json:"inputs,omitempty"`
// Outputs are the structured results this run wrote to the workflow's
// declared outputs (docs/prds/workflow-call-outputs.md). The set is
// attempt-scoped: a claim starts the next attempt with an empty set and
// the finish write replaces the row's set wholesale. Callers read these
// only from a successful terminal state, through WorkflowCallStatus.
Outputs map[string]any `json:"outputs,omitempty"`
// ReviewPayload is the JSON-encoded review unit (the forge review's
// actionable comments) the remediate workflow's current run must
// address. The daemon's reaction consumer injects it before queuing a
// remediation run, so the run is recoverable from the task record
// itself rather than only from a prompt (docs/prds/pr-review-remediation.md
// decision 4). Empty outside a remediation run. RetryCount doubles as
// the remediation round counter for this same task, bounded by the
// repo's existing max_retries (decision 5's round cap).
ReviewPayload string `json:"review_payload"`
// ParkClass is the producer-recorded answer to "what kind of
// intervention does this park need?" (taskstate.ParkClass). Set at the
// park site, never inferred from reason text; needs_human is the
// default an unclassified park reads as.
ParkClass string `json:"park_class"`
// RemediationRounds counts review-triggered remediation rounds,
// bounded by the repo's max_retries (pr-review-remediation.md
// decision 5). Deliberately separate from RetryCount, the operator
// budget: one shared counter made N operator retries eat the
// review-remediation budget and vice versa.
RemediationRounds int `json:"remediation_rounds"`
// ReviewGate is the operator-approval gate's whole conversation with
// the operator, persisted as one JSON document (prreview.EncodeReviewGate):
// the offer the gate writes before it waits for an operator -- the scored
// findings, the head SHA, the pull request's identity and the workflow the
// wait resumes -- and the answer the response path fills in -- the outcome,
// the selected findings' keys for an approve and the instructions for a
// re-review. Without it, "post the selected findings" cannot mean the
// findings the operator saw: the resumed run recomputes them with agent
// calls (docs/prds/pr-review-operator-response.md, "The review the operator
// answers"). Empty for a task that never reached the gate.
ReviewGate string `json:"review_gate"`
// RereviewRounds counts how many operator re-reviews the pr-review gate
// granted, incremented in the same guarded write that requeues the
// re-review and capped at prreview.MaxRereviewRounds
// (docs/prds/pr-review-operator-response.md, Decision 2). Deliberately
// separate from both RetryCount and RemediationRounds -- one shared
// counter made unrelated retries draw another phase's budget down.
RereviewRounds int `json:"rereview_rounds"`
// CallParentTaskID is the task whose workflow.call step started this
// one; 0 on a root run. A caller reads only the tasks it started,
// through WorkflowCallStatus.
CallParentTaskID int64 `json:"call_parent_task_id,omitempty"`
// CallDepth counts workflow.call hops from the root run. The engine
// refuses a call past workflow.MaxCallDepth, and the store re-checks on
// insert, so no enqueue path can pass the limit.
CallDepth int `json:"call_depth,omitempty"`
// CreatedAt and UpdatedAt are the SQLite row timestamps, exposed so
// callers can show a task's age and last activity. They are written by
// column defaults and the UPDATE statements, never by the caller.
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
// SourceForge and SourceChat are the valid values for Task.Source.
// Legacy rows and forge-polled tasks have Source == SourceForge (the
// zero value defaults there via the SQLite column default).
const (
SourceForge = "forge"
SourceChat = "chat"
)
// IsForgeBacked reports whether t corresponds to a real forge issue.
// Chat-spawned tasks (Source == SourceChat) have a synthetic
// IssueNumber and must not be used in forge label/comment/reply calls.
func (t Task) IsForgeBacked() bool {
return t.Source != SourceChat
}
// EffectivePRNumber resolves the pull request a pr-review task targets:
// PRNumber when a producer already set it directly (archie's own PRs, which
// never goes through binding/chat input assignment), otherwise the pr_number
// input a binding (watched repositories) or a chat task (the operator
// trigger) assigned generically through Inputs. Returns 0 when neither is
// set. DecodeInputs (the store's round-trip) decodes a JSON number as
// json.Number; a caller that built Inputs by hand in Go may use float64 or
// int instead, so all three are accepted.
func (t Task) EffectivePRNumber() int {
if t.PRNumber != 0 {
return t.PRNumber
}
switch n := t.Inputs["pr_number"].(type) {
case json.Number:
i, err := n.Int64()
if err != nil {
return 0
}
return int(i)
case float64:
return int(n)
case int:
return n
default:
return 0
}
}
// Store is the narrow, consumer-owned subset of the State Store contract
// that workflow stages call mid-run. The PostgreSQL store and staterpc.Client
// satisfy it; this is the interface archie-agent uses over the gRPC State
// Store contract. It supersedes store.WorkflowStore.
type Store interface {
Update(ctx context.Context, t *Task) error
Transition(ctx context.Context, taskID int64, from, to, detail string) error
InsertEvent(ctx context.Context, e events.Event) (int64, error)
// StartStep records a StepExecution entering running
// (docs/prds/execution-tree-state-machine.md): the store creates the row,
// enforces the step transition table and the execution's own status, and
// writes the transition's stage_start event in the same transaction. It
// returns the step's id and the persisted event, which the caller publishes
// to its bus after the write commits.
StartStep(ctx context.Context, s StepStart) (int64, events.Event, error)
// FinishStep moves one step to its outcome under the same table, writing
// the stage_finish event in the same transaction, and returns that event
// for the caller's post-commit publish.
FinishStep(ctx context.Context, s StepFinish) (events.Event, error)
}
// Definition is the operator-safe snapshot of an executable workflow. It
// contains only identity and stage order, never executable function values.
// It lives with the task vocabulary (not with the engine in package
// workflow) for the same reason this package exists: dashboards render
// Definitions without linking the engine.
type Definition struct {
ID string `json:"id"`
Name string `json:"name"`
Origin string `json:"origin"`
Enabled bool `json:"enabled"`
// Inputs and Repository are what the workflow declares, so a binding
// editor can offer the inputs to assign and whether to name a repository.
Inputs map[string]InputSpec `json:"inputs,omitempty"`
Repository RepositoryMode `json:"repository,omitempty"`
}
// HasRepository reports whether the task works on a repository. A task a
// binding started for a workflow with repository none (or optional, with no
// repository named) has neither owner nor repo and runs in a scratch
// workspace.
func (t Task) HasRepository() bool {
return t.Owner != "" || t.Repo != ""
}