Documentation
¶
Overview ¶
Package engine runs one role once: check, prepare, propose, judge, apply (docs/spec/role-contract.md, "One run").
Index ¶
Constants ¶
const ModelTrailer = "Workline-Model"
ModelTrailer names, in the engine's own commits, each agent and model whose answer they hold, as <agent>:<model> (claude:claude-sonnet-5).
const OwnTrailer = "Workline-Role"
OwnTrailer marks the commits the engine makes itself, naming the role, so that they do not wake the line again (docs/spec/routing.md).
Variables ¶
This section is empty.
Functions ¶
func ProposeBranch ¶ added in v0.2.2
func ProposeBranch(f forge.Forge, repo, roleName, key, title, body, trailers string, written []string) (int, error)
ProposeBranch commits the files written in the working tree on the role's branch for a task (workline/<role>/<key>), force-pushes it — unless the forge keeps its branches in the clone — opens its merge request or updates the one open, and puts the working tree back on the branch it was on. trailers end the commit's message.
Types ¶
type Options ¶
type Options struct {
Repo string // repository the role works on
RolesDir string // folder holding the roles
Role string // role name
Event string // event the role runs on
AI string // agent spec, see agent.Parse; empty = the project's setting
DefaultAI string // used when neither AI nor the project says (the user's own default)
Inputs map[string]string // name -> value, written to in/input/<name>
Targets map[string]string // name -> file an intention writes back to (e.g. the hook's message file)
Forge string // forge spec, see forge.Open; empty = the project's `forge` setting
Target *forge.Target // the issue or merge request comments and labels go on
// Branch is the one the targeted merge request comes from, when the job
// knows it without the forge (a CI job without the forge's token); else
// the forge is asked. Its branch tells a release tool's (ADR-0017).
Branch string
Scope []string // paths the task is about; a patch outside is refused
// NoApply stops after judging: the proposals and what apply needs are kept
// in the run folder, for `workline apply` in another job holding the token.
NoApply bool
// OpenMergeRequest puts what the patches wrote on a branch of the role's,
// and opens a merge request for it, or updates the one open (ADR-0006).
OpenMergeRequest bool
// PushToMergeRequest commits what the patches wrote to the branch of the
// merge request the run targets; from a fork, the diff goes in a comment.
PushToMergeRequest bool
// TamperBeforeApply changes the prepared input between propose and apply.
// It exists only for the conformance test that proves apply notices.
TamperBeforeApply bool
}
Options describe one run.
type Result ¶
type Result struct {
Status string `json:"status"`
Summary string `json:"summary,omitempty"`
Findings []verdict.Finding `json:"findings,omitempty"`
AgentCalls int `json:"agent-calls"`
Calls []agent.Call `json:"calls,omitempty"` // each call: what was asked, what answered
Applied []string `json:"applied"`
Refused []string `json:"refused"`
Handoffs []any `json:"handoffs,omitempty"` // next roles asked for; routing runs them
Notes []string `json:"notes,omitempty"` // what the agent left for a person: a round's notes each
RunDir string `json:"run-dir"`
ToApply bool `json:"to-apply,omitempty"` // judged with NoApply: `workline apply` still has work
// Pending: the run folders `workline apply` is given, one a round, when
// a run judged with NoApply went round, each round a merge request of
// its own (ADR-0013's amendment).
Pending []string `json:"pending,omitempty"`
MergeRequest int `json:"merge-request,omitempty"` // the merge request the patches went to
// contains filtered or unexported fields
}
Result is what a run reports.
func Follow ¶ added in v0.17.0
Follow keeps a role's release merge requests (fixElsewhere's, ADR-0017) on the tip of base, as a release tool keeps its own branch: run when base moves, it rebuilds each open one whose branch base moved under, by redoing the branch's change on base's new tip, and force-pushes it — the merge request stays the same (ADR-0034). A branch already on base's tip is left as it is; one a person committed to is never rebuilt over them; one whose change no longer applies is left for a person.
func Resume ¶
Resume applies what an interrupted run had not applied yet, from what that run recorded. The agent is not called again, and nothing is applied if the prepared input changed since.
func Run ¶
Run executes one run and always returns a result with a status: an error inside the run becomes a blocking finding, never a silent pass. When pre took less than there was to do and said so in in/more, and the round passed and applied something, the role goes round again: the next round sees what this one applied. Calls and applied intentions add up; a later round's finding replaces an earlier one of the same rule and place, and what a round deferred is dropped: the next round reports what is left.
Judged with NoApply for merge requests of its own (gardening in CI), a round applies nothing the next could see; it goes round again when it proposed a merge request for a task no earlier round proposed: the next round is told that task waits, as one open on the forge, and takes up what it deferred — the docs judged in parts after those judged whole (ADR-0013). Each round is a run folder to apply, in Pending.
Source Files