engine

Documentation

Index

• func FindLatestRunDirForTask(repoRoot, taskName string) (string, error)
• func ParseEvent(eventName, path string) (*types.GitHubEvent, error)
• func ParseEventFile(eventName, path string) (*types.GitHubEvent, error)
• func ProcessRunOutputs(ctx context.Context, repoRoot, runDirPath string, event *types.GitHubEvent, ...) (*types.RunResult, error)
• func PruneRunDirs(repoRoot string, maxAge time.Duration) error
• func ResolveForcedTask(repoRoot, taskName string) ([]string, error)
• func ResolveMatchingTasks(repoRoot string, event *types.GitHubEvent) ([]string, error)
• func RunTask(ctx context.Context, repoRoot string, taskName string, ...) (*types.RunResult, error)
• func SetGracefulAgentCancel(cmd *exec.Cmd)
• type ActivationMeta
  • func ReadActivationMeta(runDirPath string) (ActivationMeta, error)
• type ClaudeConversationStats
• type RunDir
  • func NewRunDir(repoRoot, taskName, eventName string) (*RunDir, error)
  • func (r *RunDir) AgentOutputPath(format string) string
  • func (r *RunDir) OpenAgentOutput(format string) (*os.File, error)
  • func (r *RunDir) SafeOutputJSONLPath() string
  • func (r *RunDir) UpdateMeta(phase types.Phase, success bool) error
  • func (r *RunDir) WriteActivationMeta(prevBranch string, branchCreated bool) error
  • func (r *RunDir) WritePrompt(prompt string) error
  • func (r *RunDir) WriteResult(res *types.RunResult) error
  • func (r *RunDir) WriteRunJSON(res *types.RunResult) error
• type RunOptions

Functions

func FindLatestRunDirForTask

func FindLatestRunDirForTask(repoRoot, taskName string) (string, error)

FindLatestRunDirForTask returns the absolute path to the newest `.wm/runs/<id>/` directory whose meta.json task_name matches taskName (newest is determined by meta.json file modtime). Used by `gh wm process-outputs --task` in CI when the exact run id is not passed as a flag. Only repoRoot/.wm/runs is searched (not WM_RUN_DIR), matching the default CI layout after checkout.

func ParseEvent

func ParseEvent(eventName, path string) (*types.GitHubEvent, error)

ParseEvent loads a GitHub event from path, or uses an empty JSON object when path is empty (neither --payload nor GITHUB_EVENT_PATH), for local quick runs.

func ParseEventFile

func ParseEventFile(eventName, path string) (*types.GitHubEvent, error)

ParseEventFile reads event JSON from path (github.event payload).

func ProcessRunOutputs

func ProcessRunOutputs(ctx context.Context, repoRoot, runDirPath string, event *types.GitHubEvent, opts *RunOptions) (*types.RunResult, error)

ProcessRunOutputs applies safe-outputs and the conclusion phase for a run directory produced by RunTask with RunOptions.AgentOnly (CI token sandbox: follow-up job with write permissions).

func PruneRunDirs

func PruneRunDirs(repoRoot string, maxAge time.Duration) error

PruneRunDirs removes run directories under repoRoot/.wm/runs older than maxAge.

func ResolveForcedTask

func ResolveForcedTask(repoRoot, taskName string) ([]string, error)

ResolveForcedTask returns [taskName] if a task with that name exists under .wm/tasks. It does not evaluate on: triggers (same semantics as local gh wm run).

func ResolveMatchingTasks

func ResolveMatchingTasks(repoRoot string, event *types.GitHubEvent) ([]string, error)

ResolveMatchingTasks returns task names that match the event.

func RunTask

func RunTask(ctx context.Context, repoRoot string, taskName string, event *types.GitHubEvent, opts *RunOptions) (*types.RunResult, error)

RunTask executes one task: activation (validation, branch prep), agent, validation, safe-outputs, and deferred conclusion (checkpoint, branch rollback).

func SetGracefulAgentCancel

func SetGracefulAgentCancel(cmd *exec.Cmd)

SetGracefulAgentCancel configures SIGTERM on context cancel (exported for tests).

Types

type ActivationMeta

type ActivationMeta struct {
	PrevBranch    string `json:"prev_branch"`
	BranchCreated bool   `json:"branch_created"`
}

ActivationMeta is persisted when a feature branch is created before the agent runs (for CI rollback).

func ReadActivationMeta

func ReadActivationMeta(runDirPath string) (ActivationMeta, error)

ReadActivationMeta reads activation.json if present.

type ClaudeConversationStats

type ClaudeConversationStats struct {
	EventCount   int
	EventsByType map[string]int
	ParseErrors  int
	LastResult   *claudeResultSnapshot
	// RawLines holds non-empty lines from conversation.jsonl (or one line for conversation.json) for step-summary display.
	RawLines []string
}

ClaudeConversationStats aggregates parsed Claude Code print-mode output (json / stream-json).

type RunDir

type RunDir struct {
	Path string
}

RunDir is a per-run artifact directory under .wm/runs/<id>/ or WM_RUN_DIR/<id>/.

func NewRunDir

func NewRunDir(repoRoot, taskName, eventName string) (*RunDir, error)

NewRunDir creates a unique run directory, writes initial meta.json, and prunes old runs.

func (*RunDir) AgentOutputPath

func (r *RunDir) AgentOutputPath(format string) string

AgentOutputPath returns the path to the combined agent stdout/stderr capture file for this run.

func (*RunDir) OpenAgentOutput

func (r *RunDir) OpenAgentOutput(format string) (*os.File, error)

OpenAgentOutput creates or truncates the agent output file for writing (see agentArtifactFilename).

func (*RunDir) SafeOutputJSONLPath

func (r *RunDir) SafeOutputJSONLPath() string

SafeOutputJSONLPath returns the path for NDJSON safe-output lines from `gh wm emit` (WM_SAFE_OUTPUT_FILE).

func (*RunDir) UpdateMeta

func (r *RunDir) UpdateMeta(phase types.Phase, success bool) error

UpdateMeta writes phase and optional success flag to meta.json.

func (*RunDir) WriteActivationMeta

func (r *RunDir) WriteActivationMeta(prevBranch string, branchCreated bool) error

WriteActivationMeta writes activation.json when a feature branch was created for create-pull-request.

func (*RunDir) WritePrompt

func (r *RunDir) WritePrompt(prompt string) error

WritePrompt writes the assembled agent prompt.

func (*RunDir) WriteResult

func (r *RunDir) WriteResult(res *types.RunResult) error

WriteResult writes a JSON snapshot of the run outcome (errors as strings).

func (*RunDir) WriteRunJSON

func (r *RunDir) WriteRunJSON(res *types.RunResult) error

WriteRunJSON merges meta.json fields with the run outcome (same payload as result.json plus meta header).

type RunOptions

type RunOptions struct {
	// LogWriter receives a live copy of the agent subprocess combined stdout+stderr.
	// When nil, output is buffered until the process exits.
	LogWriter io.Writer
	// ProgressWriter receives human-readable phase lines (e.g. from gh wm run); not mixed with LogWriter.
	ProgressWriter io.Writer
	// AgentOnly stops after a successful agent validation phase: skips safe-outputs and defers conclusion.
	// Used with CI token sandbox: a follow-up `gh wm process-outputs` run applies outputs with a write token.
	AgentOnly bool
}

RunOptions configures optional behavior for RunTask (e.g. CLI streaming).