Files
archie/modules/runs/dry.go
T
samandCopilot 64dfad6d53 feat(runs): add typed results and model aliases (#2043)
Also fix repository-free message.send validation (#2046) and add a single-binary development smoke path (#1977).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-18 23:47:35 +11:00

237 lines
7.3 KiB
Go

package runs
import (
"context"
"encoding/json/jsontext"
json "encoding/json/v2"
"errors"
"fmt"
"strings"
"time"
"github.com/google/uuid"
"github.com/samcharles93/archie-core/modules/deliveries"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/judgement"
"github.com/samcharles93/archie-core/modules/runs/internal/store"
)
// dryOverlay contains the workflow document and policy a dry run tests as
// if they were published.
type dryOverlay struct {
Document string `json:"document"`
PolicyKind string `json:"policy_kind,omitzero"`
Policy string `json:"policy,omitzero"`
}
func (o *dryOverlay) policy() *judgement.PolicyOverlay {
if o == nil || o.Policy == "" {
return nil
}
return &judgement.PolicyOverlay{Kind: o.PolicyKind, Body: o.Policy}
}
func readOverlay(raw jsontext.Value) (*dryOverlay, error) {
var o dryOverlay
if err := json.Unmarshal(raw, &o); err != nil {
return nil, fmt.Errorf("read dry run overlay: %w", err)
}
return &o, nil
}
// Dry reports whether the run is a dry run. Dry runs evaluate actions but
// execute only read-only actions, and send no approval requests or notifications.
func (rc *Context) Dry() bool { return rc.run.Dry }
func (rc *Context) mayExecute(d judgement.Decision) bool {
return !rc.run.Dry || d.Action.Effect.ReadOnly
}
// request asks judgement to decide an action of this run.
func (rc *Context) request(key, connector, action string, input jsontext.Value) judgement.Request {
diagnosis, evidence := rc.Rationale()
return judgement.Request{
RunID: rc.run.ID, Key: key, Connector: connector, Action: action, Input: input,
Workflow: rc.run.Workflow, Dry: rc.run.Dry, Overlay: rc.overlay.policy(),
Diagnosis: diagnosis, Evidence: evidence,
}
}
// DryRequest starts a dry run of a document that is not yet published.
type DryRequest struct {
OrgID string
// Workflow is the name the document would be published under; hard rules
// see it as the principal.
Workflow string
Document string
PolicyKind string
Policy string
Input jsontext.Value
}
// StartDry queues a dry run of a document and returns its run's id. A document
// that doesn't validate starts nothing.
func (e *Engine) StartDry(ctx context.Context, req DryRequest) (uuid.UUID, error) {
if err := e.validateDocument(ctx, req.Document); err != nil {
return uuid.Nil, err
}
overlay, err := json.Marshal(dryOverlay{Document: req.Document, PolicyKind: req.PolicyKind, Policy: req.Policy})
if err != nil {
return uuid.Nil, fmt.Errorf("encode overlay: %w", err)
}
input := req.Input
if len(input) == 0 {
input = jsontext.Value("null")
}
return e.db.Start(ctx, store.NewRun{
OrgID: req.OrgID, Workflow: req.Workflow, Input: input, Dry: true, Overlay: overlay,
})
}
// The outcomes a dry run reports for an action.
const (
// DryRan is an action that only reads, which ran for real.
DryRan = "ran"
// DryWouldRun is an action that changes something and judgement lets run
// unattended. It was not executed.
DryWouldRun = "would_run"
// DryWouldAsk is an action judgement holds for approval.
DryWouldAsk = "would_ask"
// DryRefused is an action judgement or a hard rule refuses.
DryRefused = "refused"
)
// DryAction is one action a dry run judged.
type DryAction struct {
Action string `json:"action"`
Target string `json:"target"`
Summary string `json:"summary,omitzero"`
Level string `json:"level"`
Outcome string `json:"outcome"`
// Why is what held or refused the action.
Why string `json:"why,omitzero"`
// Ask is the people who would be asked, in order.
Ask []string `json:"ask,omitzero"`
}
// DryNotice is the message a dry run would have sent.
type DryNotice struct {
Title string `json:"title"`
Body string `json:"body"`
}
// DryReport records evaluated actions, their outcomes and unsent notifications.
type DryReport struct {
RunID uuid.UUID `json:"run_id"`
State string `json:"state"`
Error string `json:"error,omitzero"`
Findings string `json:"findings,omitzero"`
Actions []DryAction `json:"actions"`
Notice *DryNotice `json:"notice,omitzero"`
At time.Time `json:"at"`
}
// DryReport returns the results recorded so far. It reports ok=false if the
// ID does not identify a dry run.
func (e *Engine) DryReport(ctx context.Context, orgID string, id uuid.UUID) (rep DryReport, ok bool, err error) {
run, found, err := e.db.Detail(ctx, orgID, id)
if err != nil || !found || !run.Dry {
return DryReport{}, false, err
}
steps, err := e.db.RecordedSteps(ctx, id)
if err != nil {
return DryReport{}, false, err
}
decisions, err := e.deps.Judge.ForRun(ctx, id)
if err != nil {
return DryReport{}, false, err
}
rep = DryReport{RunID: id, State: run.State, Error: run.Error.String, At: run.CreatedAt, Actions: make([]DryAction, 0, len(decisions))}
var result AgentResult
if json.Unmarshal(run.Result, &result) == nil {
rep.Findings = result.Answer
}
asked := map[string][]string{}
for _, s := range steps {
if key, isAsk := strings.CutPrefix(s.Name, "would-ask:"); isAsk {
var path []governance.PathStep
if json.Unmarshal(s.Output, &path) == nil {
asked[key] = pathNames(path)
}
}
if s.Name == "notify" && s.Outcome == store.OutcomeDone {
var n deliveries.Notification
if json.Unmarshal(s.Output, &n) == nil {
rep.Notice = &DryNotice{Title: n.Title, Body: n.Body}
}
}
}
for _, d := range decisions {
rep.Actions = append(rep.Actions, dryAction(d, asked[d.Key]))
}
return rep, true, nil
}
func dryAction(d judgement.Decision, ask []string) DryAction {
a := DryAction{
Action: d.Action.Connector + " " + d.Action.Name,
Target: d.Action.Target.Kind + ":" + d.Action.Target.ID,
Summary: d.Action.Effect.Summary,
Level: d.Level.String(),
Ask: ask,
}
switch {
case d.Level == judgement.Never:
a.Outcome, a.Why = DryRefused, firstText(d.Reason, "refused")
case d.Level.Runs() && d.Action.Effect.ReadOnly:
a.Outcome = DryRan
case d.Level.Runs():
a.Outcome = DryWouldRun
default:
a.Outcome, a.Why = DryWouldAsk, findingsOf(d)
}
return a
}
func pathNames(path []governance.PathStep) []string {
names := make([]string, 0, len(path))
for _, s := range path {
names = append(names, firstText(s.Name, s.Person))
}
return names
}
// settleDry records the intended approvers without sending requests.
func settleDry(rc *Context, judge Judge, settings Settings, settled map[string]bool) ([]approvalOutcome, error) {
held, err := heldSince(rc, judge, settled)
if err != nil {
return nil, err
}
out := make([]approvalOutcome, 0, len(held))
for _, d := range held {
path, err := rc.Step("would-ask:"+d.Key, func(ctx context.Context, _ string) ([]governance.PathStep, error) {
return settings.EscalationPath(ctx, d.Owner(), d.Level == judgement.Escalate)
})
if err != nil {
return nil, err
}
out = append(out, approvalOutcome{
Action: d.Action.Connector + " " + d.Action.Name,
Target: d.Action.Target.Kind + ":" + d.Action.Target.ID,
State: wouldAsk(path), digest: d.Action.Digest,
})
}
return out, nil
}
// wouldAsk says who a request would go to.
func wouldAsk(path []governance.PathStep) string {
if len(path) == 0 {
return "would ask the channels"
}
return "would ask " + strings.Join(pathNames(path), ", then ")
}
var errNoDeps = errors.New("the engine has no steps to run: Use was not called")