task

package
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: Sep 6, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package task contains durable task state, exact repository observations, and short ownership-safe task locks. Provider calls deliberately do not live in this package: callers take a token, release the lock, call the provider, and use the token for the compare-and-swap completion.

Index

Constants

View Source 
const (
	PhasePlanned             = "planned"
	PhasePlanReviewing       = "plan_reviewing"
	PhasePlanApproved        = "plan_approved"
	PhaseAwaitingApproval    = "awaiting_approval"
	PhaseImplementing        = "implementing"
	PhaseNeedsInput          = "needs_input"
	PhaseImplementationReady = "implementation_ready"
	PhaseCodeReviewing       = "code_reviewing"
	PhaseApproved            = "approved"
	PhaseReviewNeeded        = "review_needed"
	PhaseFailed              = "failed"
)
View Source 
const (
	ComplexityTrivial = "trivial"
	ComplexitySmall   = "small"
	ComplexityMedium  = "medium"
	ComplexityLarge   = "large"
	ComplexitySystem  = "system"
)
View Source 
const ApprovalGateSchemaVersion = 1

ApprovalGateSchemaVersion is the schema version used by newly written approval gates. A zero value remains valid for tasks written before approval gates were persisted.

Variables

View Source 
var (
	ErrInvalidGateID           = errors.New("invalid approval gate id")
	ErrInvalidArtifactDigest   = errors.New("invalid approval artifact digest")
	ErrArtifactConflict        = errors.New("approval artifact conflicts with existing bytes")
	ErrArtifactCorrupt         = errors.New("approval artifact content digest mismatch")
	ErrApprovalArtifactMissing = errors.New("approval artifact not found")
	ErrInvalidArtifactPath     = errors.New("invalid approval artifact path")
	ErrPrivatePath             = errors.New("private RoleMux path contains a symlink or non-directory")
)
View Source 
var (
	ErrNotFound          = errors.New("task not found")
	ErrTaskExists        = errors.New("task already exists")
	ErrInvalidTaskID     = errors.New("invalid task id")
	ErrOperationInFlight = errors.New("task operation is already in flight")
	ErrStaleOperation    = errors.New("stale task operation")
	ErrInvalidPhase      = errors.New("invalid task phase")
	ErrScopeChanged      = errors.New("task scope changed during review barrier")
	ErrNotGitRepository  = errors.New("not inside a git worktree")
)

Functions

func BuildCodeApprovalArtifact added in v0.1.2 

func BuildCodeApprovalArtifact(st State, record ApprovalRecord) ([]byte, error)

BuildCodeApprovalArtifact creates the exact bytes used by the code gate. It is based only on the saved candidate projection, findings, diagnostics, and approval evidence.

func BuildPlanApprovalArtifact added in v0.1.2 

func BuildPlanApprovalArtifact(st State, record ApprovalRecord) ([]byte, error)

BuildPlanApprovalArtifact creates the exact bytes used by the plan gate. It does not consult the repository or a provider.

func CanonicalScope 

func CanonicalScope(raw string) (string, error)

CanonicalScope normalizes comma/newline separated repository-relative paths/globs. The default scope is ** and excludes all RoleMux/Git state. An explicit scope may name only the tracked project artifacts under .rolemux/plans; tracking is enforced by the manifest observer.

func DiscoverRepository 

func DiscoverRepository(start string) (string, error)

DiscoverRepository is the public repository boundary. It resolves nested working directories to the top level and fails closed for bare repositories and paths outside a Git worktree.

func HashManifest 

func HashManifest(entries []FileEntry) string

HashManifest is derived solely from path, kind, worktree content/mode, and index blob/mode/stages. Git status labels, HEAD, timestamps, and ref paths cannot change this hash.

func HashWorktreeManifest added in v0.1.2 

func HashWorktreeManifest(entries []FileEntry) string

HashWorktreeManifest identifies checked-out content independently of Git's staging state. Deleted paths and structural directories have no checked-out content. A submodule's index object is its checked-out identity.

func IntegrationTaskID 

func IntegrationTaskID(parentID string) string

func ManifestChanged 

func ManifestChanged(before, after []FileEntry) bool

func NewToken 

func NewToken() string

func NormalizeComplexity added in v0.1.2 

func NormalizeComplexity(complexity string) string

func PlanPath added in v0.1.2 

func PlanPath(repoRoot, id string) (string, error)

PlanPath resolves the compatibility plan path in private Git state. It has no side effects, so callers can use it to persist the resolved path in a record before calling WritePlan.

func ResolvePlanPath added in v0.1.2 

func ResolvePlanPath(repoRoot, id string) (string, error)

ResolvePlanPath is an explicit-name compatibility alias for PlanPath.

func ScopeMatches 

func ScopeMatches(scope, repoPath string) bool

ScopeMatches uses slash-separated paths and supports * (one segment) and ** (zero or more segments). A literal directory matches descendants.

func ScopePatterns 

func ScopePatterns(scope string) []string

func ScopeSpecHash 

func ScopeSpecHash(scope string) string

func ScopesOverlap 

func ScopesOverlap(a, b string) bool

ScopesOverlap is conservative and advisory only. It never rejects a different task ID or serializes a provider call.

func StateFingerprint 

func StateFingerprint(st State) string

func UnmatchedScopePatterns 

func UnmatchedScopePatterns(entries []FileEntry, scope string) []string

func ValidateComplexity added in v0.1.2 

func ValidateComplexity(complexity string) error

ValidateComplexity keeps planner sizing machine-readable and stable across providers. Empty remains valid for durable tasks created before sizing was introduced.

func ValidateScope 

func ValidateScope(scope string) error

func ValidateWorkUnits 

func ValidateWorkUnits(units []WorkUnit) error

func ValidateWorkUnitsForComplexity added in v0.1.2 

func ValidateWorkUnitsForComplexity(complexity string, units []WorkUnit) error

ValidateWorkUnitsForComplexity prevents a planner from turning a local change into a miniature program. Large plans remain free to use the graph they need.

func WorkTaskID 

func WorkTaskID(parentID, unitID string) string

func WorkUnitCriticalPath added in v0.1.2 

func WorkUnitCriticalPath(units []WorkUnit) ([]string, int, error)

WorkUnitCriticalPath returns the deterministic longest dependency path by planner-supplied focused minutes. It is scheduling guidance, not a promise.

func WorkUnitWaves 

func WorkUnitWaves(units []WorkUnit) ([][]string, error)

WorkUnitWaves returns deterministic topological layers. Every unit in one layer can be scheduled concurrently after all earlier layers are approved.

func WritePlan 

func WritePlan(repoRoot, id, contents string) error

WritePlan performs a same-directory durable atomic plan write. The caller must pass a validated task ID; no arbitrary path is accepted.

func WritePlanPath added in v0.1.2 

func WritePlanPath(repoRoot, id string) (string, error)

WritePlanPath is a descriptive compatibility alias for PlanPath.

Types

type AdvisoryLock 

type AdvisoryLock struct {
	// contains filtered or unexported fields
}

func (*AdvisoryLock) Unlock 

func (l *AdvisoryLock) Unlock() error

type ApprovalArtifactRef added in v0.1.2 

type ApprovalArtifactRef = ContentRef

type ApprovalChangedFile added in v0.1.2 

type ApprovalChangedFile struct {
	Path       string `json:"path"`
	Kind       string `json:"kind,omitempty"`
	ChangeKind string `json:"change_kind,omitempty"`
}

ApprovalChangedFile is the compact changed-file context carried by an approval. It intentionally does not contain file bytes or immutable content references.

type ApprovalDecision added in v0.1.2 

type ApprovalDecision string
const (
	ApprovalDecisionApprove        ApprovalDecision = "approve"
	ApprovalDecisionRequestChanges ApprovalDecision = "request_changes"
	ApprovalDecisionDiscuss        ApprovalDecision = "discuss"

	ApprovalApprove        ApprovalDecision = ApprovalDecisionApprove
	ApprovalRequestChanges ApprovalDecision = ApprovalDecisionRequestChanges
	ApprovalDiscuss        ApprovalDecision = ApprovalDecisionDiscuss
	DecisionApprove        ApprovalDecision = ApprovalDecisionApprove
	DecisionRequestChanges ApprovalDecision = ApprovalDecisionRequestChanges
	DecisionDiscuss        ApprovalDecision = ApprovalDecisionDiscuss
)

type ApprovalFileChange added in v0.1.2 

type ApprovalFileChange = ApprovalChangedFile

type ApprovalKind added in v0.1.2 

type ApprovalKind string
const (
	ApprovalKindPlan ApprovalKind = "plan"
	ApprovalKindCode ApprovalKind = "code"

	// Short aliases keep the values convenient for callers that already use
	// the domain words as constants.
	ApprovalPlan ApprovalKind = ApprovalKindPlan
	ApprovalCode ApprovalKind = ApprovalKindCode
)

type ApprovalRecord added in v0.1.2 

type ApprovalRecord struct {
	GateID               string                `json:"gate_id"`
	Kind                 ApprovalKind          `json:"kind"`
	Status               ApprovalDecision      `json:"status,omitempty"`
	ArtifactRef          string                `json:"artifact_ref,omitempty"`
	ArtifactDigest       string                `json:"artifact_digest,omitempty"`
	Artifact             *ContentRef           `json:"artifact,omitempty"`
	SubjectFingerprint   string                `json:"subject_fingerprint,omitempty"`
	Question             string                `json:"question,omitempty"`
	Choices              []string              `json:"choices,omitempty"`
	Scope                string                `json:"scope,omitempty"`
	ChangedPaths         []string              `json:"changed_paths,omitempty"`
	ChangedFiles         []ApprovalChangedFile `json:"changed_files,omitempty"`
	ReviewerEvidence     *ReviewerEvidence     `json:"reviewer_evidence,omitempty"`
	ExternalReview       *ExternalReview       `json:"external_review,omitempty"`
	CreatedAt            time.Time             `json:"created_at,omitempty"`
	DecidedAt            *time.Time            `json:"decided_at,omitempty"`
	HumanFeedback        string                `json:"human_feedback,omitempty"`
	FeedbackOperationRef string                `json:"feedback_operation_ref,omitempty"`
}

ApprovalRecord is the durable human-approval gate. An absent record is distinct from a record with an approval decision: loading legacy JSON never invents a human decision.

type BudgetIssue added in v0.1.2 

type BudgetIssue struct {
	Role     string `json:"role"`
	Kind     string `json:"kind"`
	Limit    int64  `json:"limit"`
	Observed int64  `json:"observed"`
	Message  string `json:"message"`
}

type ChangedFile added in v0.1.2 

type ChangedFile = ApprovalChangedFile

type CodeApprovalArtifact added in v0.1.2 

type CodeApprovalArtifact struct {
	SchemaVersion            int                   `json:"schema_version"`
	GateID                   string                `json:"gate_id"`
	Kind                     ApprovalKind          `json:"kind"`
	SubjectFingerprint       string                `json:"subject_fingerprint,omitempty"`
	CandidateFingerprint     string                `json:"candidate_fingerprint"`
	Question                 string                `json:"question,omitempty"`
	Choices                  []string              `json:"choices,omitempty"`
	Scope                    string                `json:"scope"`
	ChangedPaths             []string              `json:"changed_paths"`
	ChangedFiles             []ApprovalChangedFile `json:"changed_files"`
	ReviewerEvidence         *ReviewerEvidence     `json:"reviewer_evidence,omitempty"`
	Findings                 []Finding             `json:"findings,omitempty"`
	ReviewCheckpointFindings []Finding             `json:"review_checkpoint_findings,omitempty"`
	Advisories               []Diagnostic          `json:"advisories,omitempty"`
	Diagnostics              []string              `json:"diagnostics,omitempty"`
}

CodeApprovalArtifact is the compact code-review report. It carries the candidate identity and review evidence without serializing State, provider sessions, credentials, or conversation transcripts.

type ContentRef 

type ContentRef struct {
	Digest string `json:"digest"`
	Path   string `json:"path"`
	Size   int64  `json:"size"`
}

ContentRef points at an immutable, content-addressed copy in private RoleMux state. Baseline and candidate roots are separate by construction.

type ContentState 

type ContentState struct {
	Present bool        `json:"present"`
	Mode    string      `json:"mode,omitempty"`
	Hash    string      `json:"hash,omitempty"`
	Size    int64       `json:"size,omitempty"`
	Ref     *ContentRef `json:"ref,omitempty"`
}

type Diagnostic 

type Diagnostic struct {
	Code     string   `json:"code"`
	Severity string   `json:"severity"`
	Message  string   `json:"message"`
	TaskID   string   `json:"task_id,omitempty"`
	Paths    []string `json:"paths,omitempty"`
}

Diagnostic is advisory. It never causes RoleMux to stash, revert, commit, merge, or globally serialize an unrelated task.

type ExternalReview added in v0.1.2 

type ExternalReview struct {
	Provider                      string    `json:"provider"`
	URL                           string    `json:"url"`
	Number                        int       `json:"number"`
	Repository                    string    `json:"repository"`
	Remote                        string    `json:"remote"`
	BaseBranch                    string    `json:"base_branch"`
	HeadBranch                    string    `json:"head_branch"`
	BaseCommit                    string    `json:"base_commit"`
	HeadCommit                    string    `json:"head_commit"`
	PublishedCandidateFingerprint string    `json:"published_candidate_fingerprint"`
	LastIssueCommentID            int64     `json:"last_issue_comment_id,omitempty"`
	LastReviewCommentID           int64     `json:"last_review_comment_id,omitempty"`
	LastReviewID                  int64     `json:"last_review_id,omitempty"`
	PublishedAt                   time.Time `json:"published_at"`
	LastSyncedAt                  time.Time `json:"last_synced_at,omitempty"`
}

ExternalReview tracks an optional human-review surface. It contains only public repository coordinates and synchronization cursors; credentials are always owned by the host CLI.

type FileEntry 

type FileEntry struct {
	Path   string `json:"path"`
	Kind   string `json:"kind"`
	Status string `json:"status,omitempty"`
	Mode   string `json:"mode,omitempty"`
	Hash   string `json:"hash,omitempty"`
	Size   int64  `json:"size,omitempty"`

	Worktree ContentState `json:"worktree,omitempty"`
	Index    IndexState   `json:"index,omitempty"`
}

FileEntry is an exact worktree/index observation. Status is only a derived advisory label and is intentionally excluded from HashManifest. The legacy top-level fields are retained in JSON for small embedders that used the first preview API; new code should use Worktree and Index.

func CaptureContentRefs 

func CaptureContentRefs(entries []FileEntry, repoRoot, privateRoot, label, taskID string) ([]FileEntry, error)

CaptureContentRefs stores baseline/candidate worktree bytes in separate immutable roots. It does not alter the entries supplied by another snapshot.

func CaptureIndexRefs 

func CaptureIndexRefs(entries []FileEntry, repoRoot, privateRoot, label, taskID string) ([]FileEntry, error)

CaptureIndexRefs copies staged blobs from the index into a distinct immutable root. Deleted worktree entries can therefore still be reviewed after HEAD moves.

func ScopeEntries 

func ScopeEntries(entries []FileEntry, scope string) []FileEntry

type Finding 

type Finding struct {
	Severity string `json:"severity,omitempty"`
	Path     string `json:"path,omitempty"`
	Line     int    `json:"line,omitempty"`
	Message  string `json:"message"`
}

type InFlight 

type InFlight struct {
	Token            string      `json:"token"`
	Operation        string      `json:"operation"`
	Role             string      `json:"role"`
	OwnerPID         int         `json:"owner_pid,omitempty"`
	StartedAt        time.Time   `json:"started_at"`
	KnownSession     bool        `json:"known_session"`
	SessionID        string      `json:"session_id,omitempty"`
	SnapshotManifest []FileEntry `json:"snapshot_manifest,omitempty"`
	PreviousPhase    string      `json:"previous_phase,omitempty"`
	Prompt           string      `json:"prompt,omitempty"`
	Findings         []Finding   `json:"findings,omitempty"`
	Scope            string      `json:"scope,omitempty"`
	Loop             string      `json:"loop,omitempty"`
}

type IndexStage 

type IndexStage struct {
	Stage int         `json:"stage"`
	Mode  string      `json:"mode"`
	Blob  string      `json:"blob"`
	Ref   *ContentRef `json:"ref,omitempty"`
}

type IndexState 

type IndexState struct {
	Present bool         `json:"present"`
	Mode    string       `json:"mode,omitempty"`
	Blob    string       `json:"blob,omitempty"`
	Stages  []int        `json:"stages,omitempty"`
	Ref     *ContentRef  `json:"ref,omitempty"`
	Entries []IndexStage `json:"entries,omitempty"`
}

type ManifestDeltaResult 

type ManifestDeltaResult struct {
	Added, Removed, Changed []FileEntry
}

func ManifestDelta 

func ManifestDelta(before, after []FileEntry) ManifestDeltaResult

func (ManifestDeltaResult) Paths 

func (d ManifestDeltaResult) Paths() []string

type PlanApprovalArtifact added in v0.1.2 

type PlanApprovalArtifact struct {
	SchemaVersion      int               `json:"schema_version"`
	GateID             string            `json:"gate_id"`
	Kind               ApprovalKind      `json:"kind"`
	SubjectFingerprint string            `json:"subject_fingerprint,omitempty"`
	Question           string            `json:"question,omitempty"`
	Choices            []string          `json:"choices,omitempty"`
	Scope              string            `json:"scope,omitempty"`
	Plan               string            `json:"plan"`
	Complexity         string            `json:"complexity,omitempty"`
	WorkUnits          []WorkUnit        `json:"work_units"`
	ReviewerEvidence   *ReviewerEvidence `json:"reviewer_evidence,omitempty"`
}

PlanApprovalArtifact is a reproducible, deliberately narrow report. It is generated from the saved task projection and approval record only.

type ProfileSnapshot 

type ProfileSnapshot struct {
	Provider string `json:"provider"`
	Model    string `json:"model"`
	Effort   string `json:"effort,omitempty"`
	Speed    string `json:"speed,omitempty"`
}

type Progress added in v0.1.2 

type Progress struct {
	Role         string    `json:"role"`
	Operation    string    `json:"operation"`
	AgentTurns   int64     `json:"agent_turns"`
	ToolCalls    int64     `json:"tool_calls"`
	LastTool     string    `json:"last_tool,omitempty"`
	Active       bool      `json:"active"`
	LastActivity time.Time `json:"last_activity"`
	// LastHeartbeat proves the owning RoleMux process is still supervising the
	// provider even when that provider does not stream reasoning activity.
	LastHeartbeat time.Time `json:"last_heartbeat,omitempty"`
}

type RetryState 

type RetryState struct {
	Token            string      `json:"token"`
	Operation        string      `json:"operation"`
	Role             string      `json:"role"`
	PreviousPhase    string      `json:"previous_phase"`
	Prompt           string      `json:"prompt,omitempty"`
	Findings         []Finding   `json:"findings,omitempty"`
	Scope            string      `json:"scope,omitempty"`
	SessionID        string      `json:"session_id,omitempty"`
	KnownSession     bool        `json:"known_session"`
	Loop             string      `json:"loop,omitempty"`
	SnapshotManifest []FileEntry `json:"snapshot_manifest,omitempty"`
	CreatedAt        time.Time   `json:"created_at"`
}

type ReviewPolicy added in v0.1.2 

type ReviewPolicy struct {
	MaxRounds int `json:"max_rounds"`
}

type ReviewProgress added in v0.1.2 

type ReviewProgress struct {
	Kind   string `json:"kind"`
	Status string `json:"status"`
}

type ReviewerEvidence added in v0.1.2 

type ReviewerEvidence struct {
	SourceTask          string           `json:"source_task,omitempty"`
	SourceTaskID        string           `json:"source_task_id,omitempty"`
	Verdict             string           `json:"verdict"`
	ReviewerRole        string           `json:"reviewer_role,omitempty"`
	ReviewerSessionID   string           `json:"reviewer_session_id,omitempty"`
	ReviewerSession     string           `json:"reviewer_session,omitempty"`
	ReviewerProfile     *ProfileSnapshot `json:"reviewer_profile,omitempty"`
	Profile             *ProfileSnapshot `json:"profile,omitempty"`
	AcceptedRound       int              `json:"accepted_round,omitempty"`
	ReviewedFingerprint string           `json:"reviewed_fingerprint,omitempty"`
}

ReviewerEvidence is copied into the approval record before it is persisted. It is evidence about a completed review, rather than a live provider session. The compatibility aliases allow old callers to retain their existing session/profile field names while the canonical fields remain explicit.

type RoleBudget added in v0.1.2 

type RoleBudget struct {
	MaxTurns       int   `json:"max_turns,omitempty" toml:"max_turns,omitempty"`
	MaxToolCalls   int   `json:"max_tool_calls,omitempty" toml:"max_tool_calls,omitempty"`
	TimeoutSeconds int   `json:"timeout_seconds,omitempty" toml:"timeout_seconds,omitempty"`
	MaxOutputBytes int64 `json:"max_output_bytes,omitempty" toml:"max_output_bytes,omitempty"`
}

RoleBudget is snapshotted when a task starts so later configuration edits cannot silently change the execution contract of an active workflow.

type RuntimeSnapshot 

type RuntimeSnapshot struct {
	ProviderType string         `json:"provider_type"`
	ProviderID   string         `json:"provider_id,omitempty"`
	Endpoint     string         `json:"endpoint,omitempty"`
	WireAPI      string         `json:"wire_api,omitempty"`
	AuthEnvRefs  []string       `json:"auth_env_refs,omitempty"`
	Auth         map[string]any `json:"auth,omitempty"`
	CLIPath      string         `json:"cli_path,omitempty"`
	SDKSettings  map[string]any `json:"sdk_settings,omitempty"`
}

RuntimeSnapshot stores routing metadata but never a credential value.

type State 

type State struct {
	ID                   string     `json:"id"`
	RepoRoot             string     `json:"repo_root"`
	Phase                string     `json:"phase"`
	Round                int        `json:"round"` // compatibility alias; plan/code are authoritative.
	Task                 string     `json:"task,omitempty"`
	Prompt               string     `json:"prompt,omitempty"`
	Plan                 string     `json:"plan,omitempty"`
	PlanHash             string     `json:"plan_hash,omitempty"`
	ApprovedPlanHash     string     `json:"approved_plan_hash,omitempty"`
	ApprovedManifestHash string     `json:"approved_manifest_hash,omitempty"`
	ParentTaskID         string     `json:"parent_task_id,omitempty"`
	WorkUnitID           string     `json:"work_unit_id,omitempty"`
	PlannedScope         string     `json:"planned_scope,omitempty"`
	IntegrationReview    bool       `json:"integration_review,omitempty"`
	WorkGraph            bool       `json:"work_graph,omitempty"`
	WorkUnits            []WorkUnit `json:"work_units,omitempty"`
	Complexity           string     `json:"complexity,omitempty"`
	DirectImplementation bool       `json:"direct_implementation,omitempty"`

	PlannerSessionID      string `json:"planner_session_id,omitempty"`
	PlanReviewerSessionID string `json:"plan_reviewer_session_id,omitempty"`
	ImplementerSessionID  string `json:"implementer_session_id,omitempty"`
	CodeReviewerSessionID string `json:"code_reviewer_session_id,omitempty"`

	LastUsedAt time.Time `json:"last_used_at,omitempty"`
	UpdatedAt  time.Time `json:"updated_at"`

	Scope                 string      `json:"scope,omitempty"`
	ScopeSpecHash         string      `json:"scope_spec_hash,omitempty"`
	ScopedBaseline        []FileEntry `json:"scoped_baseline_manifest,omitempty"`
	ScopedBaselineHash    string      `json:"scoped_baseline_manifest_hash,omitempty"`
	CandidateManifest     []FileEntry `json:"candidate_manifest,omitempty"`
	CandidateManifestHash string      `json:"candidate_manifest_hash,omitempty"`
	ChangeManifest        []FileEntry `json:"change_manifest,omitempty"`
	// ReviewCheckpoint is the exact candidate from the last completed
	// changes-requested verdict. Re-review compares fixes against this point
	// instead of making the reviewer rediscover the full task delta.
	ReviewCheckpoint          []FileEntry                `json:"review_checkpoint_manifest,omitempty"`
	ReviewCheckpointHash      string                     `json:"review_checkpoint_manifest_hash,omitempty"`
	ReviewCheckpointFindings  []Finding                  `json:"review_checkpoint_findings,omitempty"`
	PlanReviewCheckpointHash  string                     `json:"plan_review_checkpoint_hash,omitempty"`
	ProfilesSnapshot          map[string]ProfileSnapshot `json:"profiles_snapshot,omitempty"`
	RuntimeSnapshot           map[string]RuntimeSnapshot `json:"runtime_snapshot,omitempty"`
	BudgetsSnapshot           map[string]RoleBudget      `json:"budgets_snapshot,omitempty"`
	MaxRounds                 int                        `json:"max_rounds,omitempty"`
	PlanRound                 int                        `json:"plan_round,omitempty"`
	CodeRound                 int                        `json:"code_round,omitempty"`
	ReviewPolicy              *ReviewPolicy              `json:"review_policy,omitempty"`
	ReviewProgress            *ReviewProgress            `json:"review_progress,omitempty"`
	Approval                  *ApprovalRecord            `json:"approval,omitempty"`
	ApprovalHistory           []ApprovalRecord           `json:"approval_history,omitempty"`
	ApprovalGateSchemaVersion int                        `json:"approval_gate_schema_version,omitempty"`
	PendingQuestion           string                     `json:"pending_question,omitempty"`
	PendingQuestionSource     string                     `json:"pending_question_source,omitempty"`
	PendingAnswer             string                     `json:"pending_answer,omitempty"`
	PromptInputs              []string                   `json:"prompt_inputs,omitempty"`
	ReturnPhase               string                     `json:"return_phase,omitempty"`
	InterruptedLoop           string                     `json:"interrupted_loop,omitempty"`
	Findings                  []Finding                  `json:"findings,omitempty"`
	Advisories                []Diagnostic               `json:"advisories,omitempty"`
	Diagnostics               []string                   `json:"diagnostics,omitempty"`
	Usage                     map[string]TokenUsage      `json:"usage,omitempty"`
	Events                    []WorkflowEvent            `json:"events,omitempty"`
	BudgetIssue               *BudgetIssue               `json:"budget_issue,omitempty"`
	Progress                  *Progress                  `json:"progress,omitempty"`
	// ProviderUsageCumulative stores the last raw conversation-wide counters
	// for providers that report cumulative rather than per-turn usage.
	ProviderUsageCumulative map[string]TokenUsage `json:"provider_usage_cumulative,omitempty"`
	InFlight                *InFlight             `json:"in_flight,omitempty"`
	Retry                   *RetryState           `json:"retry,omitempty"`
}

State is the durable task record. Scope and its exact baseline are first established atomically by the first implement invocation.

type Store 

type Store struct {
	Root string
	Dir  string
	// contains filtered or unexported fields
}

func NewStore 

func NewStore(repoRoot string) *Store

func NewStoreAt 

func NewStoreAt(dir string) *Store

func (*Store) ApprovalArtifactPath added in v0.1.2 

func (s *Store) ApprovalArtifactPath(taskID, gateID string, digest ...string) (string, error)

ApprovalArtifactPath returns the absolute path for a content-addressed artifact. With no digest it returns the private gate directory, which is useful to callers that need to inspect or repair a gate directory.

func (*Store) ArtifactPath added in v0.1.2 

func (s *Store) ArtifactPath(taskID, gateID, digest string) (string, error)

ArtifactPath is the shorter generic spelling for ApprovalArtifactPath.

func (*Store) Create 

func (s *Store) Create(st State) error

Create rejects duplicate task IDs while holding the same task-scoped lock used by all subsequent state mutations.

func (*Store) Delete 

func (s *Store) Delete(id string) error

func (*Store) List 

func (s *Store) List() ([]State, error)

func (*Store) Load 

func (s *Store) Load(id string) (State, error)

func (*Store) Lock 

func (s *Store) Lock(id string) (*AdvisoryLock, error)

Lock holds only the requested task lock. The lock file is never unlinked, avoiding the classic create/delete race where one process removes another's lock. Callers must release it promptly and never across provider calls.

func (*Store) PersistApprovalArtifact added in v0.1.2 

func (s *Store) PersistApprovalArtifact(st State, record ApprovalRecord) (ApprovalRecord, ContentRef, error)

PersistApprovalArtifact returns a copy of the saved record with its immutable artifact reference attached. The caller can then persist that record through Store.Update; this helper does not mutate task state.

func (*Store) ReadApprovalArtifact added in v0.1.2 

func (s *Store) ReadApprovalArtifact(taskID, gateID string, digest ...string) ([]byte, error)

ReadApprovalArtifact reads and verifies a content-addressed artifact. The variadic digest keeps the directory form of ApprovalArtifactPath useful while allowing the normal three-argument read call.

func (*Store) ReadApprovalArtifactRef added in v0.1.2 

func (s *Store) ReadApprovalArtifactRef(ref ContentRef) ([]byte, error)

ReadApprovalArtifactRef verifies and reads a previously returned content reference without trusting the path or digest independently.

func (*Store) ReadContentRef added in v0.1.2 

func (s *Store) ReadContentRef(ref ContentRef) ([]byte, error)

ReadContentRef verifies and reads a captured baseline/candidate blob. The path is accepted only from RoleMux's private content root, so a modified task record cannot turn review publishing into an arbitrary file read.

func (*Store) ReadOrRepairApprovalArtifact added in v0.1.2 

func (s *Store) ReadOrRepairApprovalArtifact(taskID, gateID string, contents []byte) (ContentRef, error)

ReadOrRepairApprovalArtifact verifies an existing artifact or durably recreates it when the content-addressed file is missing.

func (*Store) ReadOrRepairArtifact added in v0.1.2 

func (s *Store) ReadOrRepairArtifact(taskID, gateID string, contents []byte) (ContentRef, error)

ReadOrRepairArtifact is a generic spelling retained for storage callers.

func (*Store) Save 

func (s *Store) Save(st State) error

func (*Store) SaveOwned 

func (s *Store) SaveOwned(st State, token string) error

func (*Store) Update 

func (s *Store) Update(id string, update func(*State) error) (State, error)

Update performs a short atomic state mutation under the task-scoped lock. The callback must not invoke providers or inspect the worktree.

func (*Store) UpdateOwned 

func (s *Store) UpdateOwned(id, token string, update func(*State) error) (State, error)

UpdateOwned performs a short atomic token/CAS mutation. The callback must not perform provider or repository operations.

func (*Store) WriteApprovalArtifact added in v0.1.2 

func (s *Store) WriteApprovalArtifact(taskID, gateID string, contents []byte) (ContentRef, error)

WriteApprovalArtifact stores immutable bytes under private Git state and returns an absolute path, digest, and byte count. Repeating the exact write is successful; an existing path containing different bytes is rejected.

func (*Store) WriteCodeApprovalArtifact added in v0.1.2 

func (s *Store) WriteCodeApprovalArtifact(st State, record ApprovalRecord) (ContentRef, error)

WriteCodeApprovalArtifact builds and stores the code report.

func (*Store) WritePlanApprovalArtifact added in v0.1.2 

func (s *Store) WritePlanApprovalArtifact(st State, record ApprovalRecord) (ContentRef, error)

WritePlanApprovalArtifact builds and stores the plan report.

type TokenUsage 

type TokenUsage struct {
	Requests           int64 `json:"requests"`
	AgentTurns         int64 `json:"agent_turns,omitempty"`
	ToolCalls          int64 `json:"tool_calls,omitempty"`
	PromptBytes        int64 `json:"prompt_bytes"`
	UnreportedRequests int64 `json:"unreported_requests,omitempty"`
	IncompleteRequests int64 `json:"incomplete_requests,omitempty"`
	InputTokens        int64 `json:"input_tokens,omitempty"`
	CachedInputTokens  int64 `json:"cached_input_tokens,omitempty"`
	CacheWriteTokens   int64 `json:"cache_write_tokens,omitempty"`
	OutputTokens       int64 `json:"output_tokens,omitempty"`
	ReasoningTokens    int64 `json:"reasoning_tokens,omitempty"`
	TotalTokens        int64 `json:"total_tokens,omitempty"`
}

TokenUsage is accumulated per workflow role. Token fields are populated only when the provider reports them; requests and prompt bytes are measured by RoleMux for every provider invocation.

func (*TokenUsage) Add 

func (u *TokenUsage) Add(turn TokenUsage)

func (TokenUsage) Empty 

func (u TokenUsage) Empty() bool

type WorkUnit 

type WorkUnit struct {
	ID                 string   `json:"id"`
	Objective          string   `json:"objective"`
	Scope              string   `json:"scope"`
	DependsOn          []string `json:"depends_on"`
	ContextGroup       string   `json:"context_group"`
	ContextFiles       []string `json:"context_files"`
	AffectedSymbols    []string `json:"affected_symbols"`
	EstimatedMinutes   int      `json:"estimated_minutes"`
	ExecutionPacket    string   `json:"execution_packet"`
	AcceptanceCriteria []string `json:"acceptance_criteria"`
	ValidationCommands []string `json:"validation_commands"`
}

WorkUnit is an execution-ready node in a planner-produced dependency graph. Scope is the node's exclusive write scope; the execution packet must carry all context the implementer needs without repeating broad repository research.

func NormalizeWorkUnits 

func NormalizeWorkUnits(units []WorkUnit, plan string) ([]WorkUnit, error)

NormalizeWorkUnits canonicalizes scopes and validates graph safety. The single-node fallback preserves old provider sessions created before planner envelopes carried a graph.

type WorkflowEvent added in v0.1.2 

type WorkflowEvent struct {
	Type       string    `json:"type"`
	Role       string    `json:"role,omitempty"`
	Operation  string    `json:"operation,omitempty"`
	Round      int       `json:"round,omitempty"`
	Message    string    `json:"message"`
	Findings   []Finding `json:"findings,omitempty"`
	OccurredAt time.Time `json:"occurred_at"`
}

WorkflowEvent is a bounded, non-secret lifecycle record. It carries coordination facts and review findings, never provider reasoning or raw tool output.

type Worktree 

type Worktree struct{ Root string }

Worktree exposes repository-relative exact observations.

func NewWorktree 

func NewWorktree(root string) *Worktree

func (*Worktree) Head 

func (w *Worktree) Head() (string, error)

func (*Worktree) Manifest 

func (w *Worktree) Manifest() ([]FileEntry, error)

func (*Worktree) ManifestForScope 

func (w *Worktree) ManifestForScope(scope string) ([]FileEntry, error)

ManifestForScope builds a HEAD-independent projection. It observes both worktree bytes and index mode/blob/stage entries, then adds structural ancestors required to explain paths. A directory's child-list hash includes only children that can affect the requested scope, so an unrelated sibling does not stale an approval.

func (*Worktree) Paths 

func (w *Worktree) Paths() ([]string, error)

Source Files

View all Source files

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.