recovery

package
v0.2.13 Latest Latest
Warning

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

Go to latest
Published: Jul 10, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package recovery defines run recovery contracts and helpers.

Index

Constants

View Source
const ResultSchemaVersion = 1

ResultSchemaVersion is the supported persisted result.json schema version.

View Source
const TimeoutExitCode = -2

TimeoutExitCode is the executor exit code used for activity timeouts.

Variables

This section is empty.

Functions

func FilterJobsBySafeName

func FilterJobsBySafeName(jobs []model.Job, failedJobIDs []string) ([]model.Job, error)

FilterJobsBySafeName keeps only prepared jobs whose SafeName appears in failedJobIDs, preserving prepared order and failing loudly on stale IDs.

func RefreshRunScopeJournal

func RefreshRunScopeJournal(ctx context.Context, scope model.RunScope) error

RefreshRunScopeJournal replaces the scope journal with a fresh append handle.

Types

type AgenticRemediation

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

AgenticRemediation launches a recovery agent through the exec pipeline.

func NewAgenticRemediation

func NewAgenticRemediation(opts ...AgenticRemediationOption) *AgenticRemediation

NewAgenticRemediation constructs the default agentic recovery strategy.

func (*AgenticRemediation) Name

func (a *AgenticRemediation) Name() string

Name returns the stable strategy name used in events and logs.

func (*AgenticRemediation) Remediate

Remediate captures a diff audit, runs the recovery agent, and parses its constrained JSON verdict.

type AgenticRemediationOption

type AgenticRemediationOption func(*AgenticRemediation)

AgenticRemediationOption configures AgenticRemediation.

func WithPreparedPromptExecutor

func WithPreparedPromptExecutor(fn preparedPromptExecutor) AgenticRemediationOption

WithPreparedPromptExecutor overrides the exec helper for tests.

type AuditMetadata

type AuditMetadata struct {
	SchemaVersion             string   `json:"schema_version"`
	Supported                 bool     `json:"supported"`
	GitAvailable              bool     `json:"git_available"`
	IsGitRepo                 bool     `json:"is_git_repo"`
	HasCommits                bool     `json:"has_commits"`
	BaselineSupported         bool     `json:"baseline_supported"`
	FinalSupported            bool     `json:"final_supported"`
	BaselineUnsupportedReason string   `json:"baseline_unsupported_reason,omitempty"`
	FinalUnsupportedReason    string   `json:"final_unsupported_reason,omitempty"`
	PreExistingDirty          bool     `json:"pre_existing_dirty"`
	PreExistingUntracked      bool     `json:"pre_existing_untracked"`
	CaptureErrors             []string `json:"capture_errors,omitempty"`
}

AuditMetadata is the JSON shape persisted as metadata.json.

type AuditSnapshot

type AuditSnapshot struct {
	SchemaVersion       string `json:"schema_version"`
	Supported           bool   `json:"supported"`
	GitAvailable        bool   `json:"git_available"`
	IsGitRepo           bool   `json:"is_git_repo"`
	HasCommits          bool   `json:"has_commits"`
	Head                string `json:"head,omitempty"`
	Branch              string `json:"branch,omitempty"`
	Digest              string `json:"digest,omitempty"`
	RawPorcelainZBase64 string `json:"raw_porcelain_z_base64"`
	UnsupportedReason   string `json:"unsupported_reason,omitempty"`
	Error               string `json:"error,omitempty"`
	// contains filtered or unexported fields
}

AuditSnapshot is the JSON shape persisted as baseline.json and final.json.

type ChangedFile

type ChangedFile struct {
	Path           string `json:"path"`
	OriginalPath   string `json:"original_path,omitempty"`
	Kind           string `json:"kind"`
	IndexStatus    string `json:"index_status"`
	WorktreeStatus string `json:"worktree_status"`
	PreExisting    bool   `json:"pre_existing"`
}

ChangedFile is one final dirty path with recovery attribution.

type ChangedFilesAudit

type ChangedFilesAudit struct {
	SchemaVersion string        `json:"schema_version"`
	Supported     bool          `json:"supported"`
	Added         []ChangedFile `json:"added"`
	Modified      []ChangedFile `json:"modified"`
	Deleted       []ChangedFile `json:"deleted"`
	Untracked     []ChangedFile `json:"untracked"`
	Renamed       []ChangedFile `json:"renamed,omitempty"`
}

ChangedFilesAudit is the JSON shape persisted as changed_files.json.

type DiffAudit

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

DiffAudit captures baseline and final git state for one recovery attempt and writes the recovery artifact subtree.

func BeginDiffAudit

func BeginDiffAudit(ctx context.Context, workspaceRoot string, artifacts model.RunArtifacts) (*DiffAudit, error)

BeginDiffAudit captures and writes the baseline snapshot before recovery remediation edits the workspace.

func (*DiffAudit) Complete

func (a *DiffAudit) Complete(ctx context.Context) (*DiffAuditResult, error)

Complete captures final git state and writes final.json, changed_files.json, and metadata.json. Git capture failures are represented in the metadata and do not fail the recovery run; artifact write failures are returned.

type DiffAuditResult

type DiffAuditResult struct {
	Baseline     AuditSnapshot     `json:"baseline"`
	Final        AuditSnapshot     `json:"final"`
	ChangedFiles ChangedFilesAudit `json:"changed_files"`
	Metadata     AuditMetadata     `json:"metadata"`
}

DiffAuditResult contains the documents written to the recovery artifact subtree.

type EventSink

type EventSink interface {
	Submit(ctx context.Context, event events.Event) error
}

EventSink persists or publishes recovery lifecycle events.

func NewRunScopeEventSink

func NewRunScopeEventSink(scope model.RunScope) EventSink

NewRunScopeEventSink creates an event sink backed by the scope journal.

type EventSinkFunc

type EventSinkFunc func(context.Context, events.Event) error

EventSinkFunc adapts a function to EventSink.

func (EventSinkFunc) Submit

func (f EventSinkFunc) Submit(ctx context.Context, event events.Event) error

Submit sends one event through f.

type JobOutcome

type JobOutcome struct {
	SafeName string    `json:"safe_name"`
	Status   RunStatus `json:"status"`
	ExitCode int       `json:"exit_code"`
	OutLog   string    `json:"stdout_log_path,omitempty"`
	ErrLog   string    `json:"stderr_log_path,omitempty"`
	Error    string    `json:"error,omitempty"`
}

JobOutcome is the typed recovery view of one persisted job result.

func (JobOutcome) TimedOut

func (j JobOutcome) TimedOut() bool

TimedOut reports whether the job failed with the timeout exit code.

type PreparedRun

type PreparedRun interface {
	Execute(ctx context.Context) (RunOutcome, error)
	RestartFailed(ctx context.Context, failedJobIDs []string) (RunOutcome, error)
}

PreparedRun is the execution seam driven by RunRecoveryOrchestrator.

type RemediationInput

type RemediationInput struct {
	Outcome      RunOutcome
	FailedConfig *model.RuntimeConfig
	Recovery     workspace.AgentRecoveryConfig
}

RemediationInput is the recovery context supplied by the orchestrator.

type RemediationStrategy

type RemediationStrategy interface {
	Name() string
	Remediate(ctx context.Context, in RemediationInput) (TriageVerdict, error)
}

RemediationStrategy attempts to remediate one failed run outcome.

type RunOutcome

type RunOutcome struct {
	RunID        string       `json:"run_id"`
	Status       RunStatus    `json:"status"`
	ArtifactsDir string       `json:"artifacts_dir"`
	ResultPath   string       `json:"result_path,omitempty"`
	Jobs         []JobOutcome `json:"jobs"`
}

RunOutcome is the typed recovery view of one persisted run result.

func ReadExecRunOutcome

func ReadExecRunOutcome(
	ctx context.Context,
	cfg *model.RuntimeConfig,
	artifacts model.RunArtifacts,
	executeErr error,
) (RunOutcome, error)

ReadExecRunOutcome reads the persisted exec run/turn artifacts as a recovery outcome. Missing or corrupt artifacts remain fail-safe: callers get the original execution error when one exists.

func ReadRunOutcome

func ReadRunOutcome(artifacts model.RunArtifacts) (*RunOutcome, error)

ReadRunOutcome reads and validates the run's persisted result.json.

A nil outcome plus a non-nil error is fail-safe: callers should skip recovery when the persisted result contract is missing, corrupt, or unsupported.

func (RunOutcome) Canceled

func (o RunOutcome) Canceled() bool

Canceled reports whether the run or any job was canceled.

func (RunOutcome) FailedJobIDs

func (o RunOutcome) FailedJobIDs() []string

FailedJobIDs returns stable job IDs for jobs that failed.

func (RunOutcome) TimedOut

func (o RunOutcome) TimedOut() bool

TimedOut reports whether any job failed with the timeout exit code.

func (RunOutcome) TimeoutJobIDs

func (o RunOutcome) TimeoutJobIDs() []string

TimeoutJobIDs returns stable job IDs for jobs that timed out.

type RunRecoveryOrchestrator

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

RunRecoveryOrchestrator drives the recovery FSM around one prepared run.

func NewRunRecoveryOrchestrator

func NewRunRecoveryOrchestrator(
	strategy RemediationStrategy,
	recovery workspace.AgentRecoveryConfig,
	opts ...RunRecoveryOrchestratorOption,
) *RunRecoveryOrchestrator

NewRunRecoveryOrchestrator constructs an FSM-backed run recovery orchestrator.

func (*RunRecoveryOrchestrator) Run

Run executes the original run and, when gated in, attempts bounded recovery.

type RunRecoveryOrchestratorOption

type RunRecoveryOrchestratorOption func(*RunRecoveryOrchestrator)

RunRecoveryOrchestratorOption configures RunRecoveryOrchestrator.

func WithFailedRunConfig

func WithFailedRunConfig(cfg *model.RuntimeConfig) RunRecoveryOrchestratorOption

WithFailedRunConfig supplies the runtime config of the original failed run.

func WithRecoveryEventSink

func WithRecoveryEventSink(sink EventSink) RunRecoveryOrchestratorOption

WithRecoveryEventSink supplies the destination for recovery lifecycle events.

func WithRecoveryLogger

func WithRecoveryLogger(log *slog.Logger) RunRecoveryOrchestratorOption

WithRecoveryLogger supplies the logger used for FSM transition logs.

type RunStatus

type RunStatus string

RunStatus mirrors the persisted executor run status strings.

const (
	// StatusSucceeded marks a run or job that completed successfully.
	StatusSucceeded RunStatus = "succeeded"
	// StatusFailed marks a run or job that failed.
	StatusFailed RunStatus = "failed"
	// StatusCanceled marks a run or job that was canceled.
	StatusCanceled RunStatus = "canceled"
	// StatusUnknown marks a job whose terminal state was unavailable.
	StatusUnknown RunStatus = "unknown"
)

type TriageVerdict

type TriageVerdict struct {
	Decision     VerdictDecision `json:"decision"`
	Reason       string          `json:"reason"`
	ChangedFiles []string        `json:"changed_files"`
}

TriageVerdict is parsed from the recovery agent's constrained JSON output.

func ParseTriageVerdict

func ParseTriageVerdict(output string) TriageVerdict

ParseTriageVerdict parses the recovery agent's constrained JSON verdict. Malformed output, missing JSON, or unknown decisions fail safe to reject.

type VerdictDecision

type VerdictDecision string

VerdictDecision is the constrained remediation outcome emitted by the recovery agent.

const (
	// VerdictReject means the agent did not apply a project-side fix.
	VerdictReject VerdictDecision = "reject"
	// VerdictFixed means the agent applied a project-side fix and the caller may
	// restart failed jobs.
	VerdictFixed VerdictDecision = "fixed"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL