Documentation
¶
Overview ¶
Package recovery defines run recovery contracts and helpers.
Index ¶
- Constants
- func FilterJobsBySafeName(jobs []model.Job, failedJobIDs []string) ([]model.Job, error)
- func RefreshRunScopeJournal(ctx context.Context, scope model.RunScope) error
- type AgenticRemediation
- type AgenticRemediationOption
- type AuditMetadata
- type AuditSnapshot
- type ChangedFile
- type ChangedFilesAudit
- type DiffAudit
- type DiffAuditResult
- type EventSink
- type EventSinkFunc
- type JobOutcome
- type PreparedRun
- type RemediationInput
- type RemediationStrategy
- type RunOutcome
- type RunRecoveryOrchestrator
- type RunRecoveryOrchestratorOption
- type RunStatus
- type TriageVerdict
- type VerdictDecision
Constants ¶
const ResultSchemaVersion = 1
ResultSchemaVersion is the supported persisted result.json schema version.
const TimeoutExitCode = -2
TimeoutExitCode is the executor exit code used for activity timeouts.
Variables ¶
This section is empty.
Functions ¶
func FilterJobsBySafeName ¶
FilterJobsBySafeName keeps only prepared jobs whose SafeName appears in failedJobIDs, preserving prepared order and failing loudly on stale IDs.
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 ¶
func (a *AgenticRemediation) Remediate(ctx context.Context, in RemediationInput) (TriageVerdict, error)
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 ¶
EventSink persists or publishes recovery lifecycle events.
func NewRunScopeEventSink ¶
NewRunScopeEventSink creates an event sink backed by the scope journal.
type EventSinkFunc ¶
EventSinkFunc adapts a function to EventSink.
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 ¶
func (o *RunRecoveryOrchestrator) Run(ctx context.Context, run PreparedRun) (RunOutcome, error)
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" )