harnessdispatch

package
v0.57.1-rc.1 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AuthCheckEvent added in v0.50.0

func AuthCheckEvent(configDir string, cfg config.ConfigReader, event *normevent.Event) normevent.Event

AuthCheckEvent returns a copy of event to pass to the authorization gate (IsEventAuthorized, IsHarnessAuthorized, FilterAuthorizedHarnesses). When the per-repo config enables OWNERS-file authorization, the copy's actor role is upgraded from the OWNERS and OWNERS_ALIASES files in the parent of configDir. The caller's event is not mutated: the upgraded role is used only for the gate, and CEL evaluation keeps seeing the collaborator-API role.

func IsAuthorized

func IsAuthorized(event *normevent.Event) bool

IsAuthorized reports whether event may dispatch a mutation harness (write threshold). It is equivalent to IsHarnessAuthorized with an empty harness role, which fails closed to write.

func IsEventAuthorized added in v0.50.0

func IsEventAuthorized(event *normevent.Event) bool

IsEventAuthorized is the event-level dispatch gate, run once per event before harness enumeration. It returns false when the event is denied for every harness: a nil event, a bot whose ADR 0107 lookup did not recognize a registered role, a human whose role lookup failed, or an actor.role below the lowest per-harness threshold (triage). A true result means at least one harness may be authorized; callers must still filter harnesses with IsHarnessAuthorized or FilterAuthorizedHarnesses.

func IsEventAuthorizedWith added in v0.54.0

func IsEventAuthorizedWith(event *normevent.Event, opts AuthOptions) bool

IsEventAuthorizedWith is IsEventAuthorized under the policy in opts.

func IsHarnessAuthorized added in v0.50.0

func IsHarnessAuthorized(event *normevent.Event, harnessRole string) bool

IsHarnessAuthorized reports whether event may dispatch a harness whose role: field is harnessRole. Event-level exceptions (GitHub label-added, recognized bots, GitHub bot review_submitted) authorize every harness; Jira label-added is such an exception only under IsHarnessAuthorizedWith with AuthOptions.JiraLabelsByEditPermission set. Event-level denials deny every harness; the remaining path requires actor.role to satisfy RequiredActorRole(harnessRole).

func IsHarnessAuthorizedWith added in v0.54.0

func IsHarnessAuthorizedWith(event *normevent.Event, harnessRole string, opts AuthOptions) bool

IsHarnessAuthorizedWith is IsHarnessAuthorized under the policy in opts.

func IsRecognizedBot added in v0.50.0

func IsRecognizedBot(actor normevent.Actor) bool

IsRecognizedBot reports whether actor is a bot whose bot-role lookup completed and resolved a registered canonical role (ADR 0107).

func KillSwitchActive

func KillSwitchActive(configDir string) (bool, error)

KillSwitchActive reads kill_switch from config in configDir.

func MergedConfigAgents

func MergedConfigAgents(configDir string) ([]config.AgentEntry, error)

MergedConfigAgents loads agent entries from per-repo config directory.

func RequiredActorRole added in v0.50.0

func RequiredActorRole(harnessRole string) normevent.ActorRole

RequiredActorRole returns the minimum actor.role a harness requires, derived from its role: field per the authorization contract's default thresholds. Observation roles (triage, review) require triage; every other role, including an empty, unknown, or custom role, requires write (fail closed).

Types

type AuthOptions added in v0.54.0

type AuthOptions struct {
	// JiraLabelsByEditPermission turns on the Jira label-added exception:
	// a Jira label-added event is authorized without a role threshold,
	// because Jira requires the Edit Issues permission to change labels.
	// Set it only when a jira authorization provider entry is present and
	// selects labels: jira_editors (its default); under allowlist or
	// project_roles the poller resolves the label author's actor.role from
	// that source and the threshold applies.
	JiraLabelsByEditPermission bool
}

AuthOptions carries the configuration-derived inputs to the dispatch gate. The zero value is the default policy: a Jira label-added event takes the per-harness role threshold like any other event.

func AuthOptionsFor added in v0.54.0

func AuthOptionsFor(cfg config.ConfigReader) AuthOptions

AuthOptionsFor derives the dispatch gate policy from the loaded config's jira authorization provider: Jira label-added events get the Edit Issues exception only when a jira provider entry is present and selects labels: jira_editors (the default for an entry). With no jira entry, or under allowlist or project_roles, they take the role threshold.

type EntityDecision added in v0.57.0

type EntityDecision struct {
	Outcome EntityOutcome
	Reason  string
}

EntityDecision is an entity-source evaluation's outcome and its reason.

func DecideEntityEligibility added in v0.57.0

func DecideEntityEligibility(ctx context.Context, ev EntityEvaluation) EntityDecision

DecideEntityEligibility evaluates an entity-source harness predicate and returns exactly one of eligible, non-match, deferred, or denied.

It never converts unresolved data to a non-match: an entity read failure, a malformed entity, or a predicate that the known data does not settle defers the candidate, while a missing gate, a failed authorization, or a predicate that is invalid or fails to evaluate denies it.

type EntityEvaluation added in v0.57.0

type EntityEvaluation struct {
	// Harness names the harness in decision reasons.
	Harness string
	// Trigger is the harness CEL predicate over entity and event.
	Trigger string
	// EntitySources reports whether the harness declares valid entity
	// sources. Without them the harness is event-only and is denied here.
	EntitySources bool
	// Event is the prompting event, or nil for an eventless evaluation
	// (scheduled discovery or a bound run's recheck), which binds event to
	// CEL null.
	Event *normevent.Event
	// Authorize runs the gate that precedes CEL: the selected harness's
	// event-actor gate when Event is set, or the trusted-origin and platform
	// eligibility gate when Event is nil. A nil Authorize or an error denies.
	Authorize func(context.Context) error
	// ResolveEntity resolves the candidate's current normalized entity after
	// authorization. An error defers the candidate; it is never a non-match.
	ResolveEntity func(context.Context) (*normentity.Entity, error)
}

EntityEvaluation is one entity-source harness predicate check: a required normalized entity and an optional prompting event.

Harnesses without entity sources are not evaluated here; they stay on the unchanged event-only path (MatchHarnesses).

type EntityOutcome added in v0.57.0

type EntityOutcome int

EntityOutcome is the final decision of one entity-source harness evaluation (ADR 0098, ADR 0147). Only EntityEligible may start a sandbox.

const (
	// EntityDenied: the evaluation is not permitted or cannot be performed —
	// no entity sources, an invalid or failing predicate, or a failed
	// authorization gate. Retrying with more data does not change it.
	EntityDenied EntityOutcome = iota
	// EntityDeferred: the entity data does not settle the predicate (unknown
	// fields, non-complete collection coverage, or a failed read). The
	// candidate stays retryable and is never recorded as a non-match.
	EntityDeferred
	// EntityNonMatch: the predicate is false for every completion of the
	// evidence.
	EntityNonMatch
	// EntityEligible: the predicate is true for every completion of the
	// evidence.
	EntityEligible
)

Entity-source evaluation outcomes. The zero value is EntityDenied so an unset decision fails closed.

func (EntityOutcome) MayStartSandbox added in v0.57.0

func (o EntityOutcome) MayStartSandbox() bool

MayStartSandbox reports whether the outcome permits sandbox launch. Only EntityEligible does.

func (EntityOutcome) String added in v0.57.0

func (o EntityOutcome) String() string

type ExecutionRef

type ExecutionRef struct {
	Agent         string          `json:"agent"`
	Role          string          `json:"role"`
	SourceRepo    string          `json:"source_repo"`
	EventType     string          `json:"event_type"`
	EventPayload  json.RawMessage `json:"event_payload"`
	TriggerSource string          `json:"trigger_source,omitempty"`
	StatusRepo    string          `json:"status_repo"`
	StatusNumber  string          `json:"status_number"`
}

ExecutionRef is the matrix payload consumed by harness-run and fullsend run.

func Dispatch

func Dispatch(ctx context.Context, opts Options) ([]ExecutionRef, error)

Dispatch evaluates authorization, kill switch, harness triggers, and returns execution refs. Returns empty slice (not error) when denied, kill-switched, or no triggers match. Returns an error when every registered harness fails to resolve or load.

func ProjectExecutionRef

func ProjectExecutionRef(agentName string, role string, event *normevent.Event) (ExecutionRef, error)

ProjectExecutionRef maps a matched harness and event to an execution ref. Harness role values must be registered in the mint service ALLOWED_ROLES policy; custom role names pass harness validation but fail token minting with HTTP 403 until mint enrollment is extended for the repo.

type Options

type Options struct {
	// ConfigDir is the fullsend config directory (e.g. ".fullsend").
	// Must be a direct child of the repo root; filepath.Dir is used
	// to locate OWNERS and OWNERS_ALIASES for authorization.
	ConfigDir string
	Event     *normevent.Event

	// FetchPolicy controls SSRF protection for URL-sourced agent harnesses.
	// When nil, fetch.DefaultPolicy is used (allows github.com and
	// raw.githubusercontent.com). Set this in tests to allow httptest domains.
	FetchPolicy *fetch.FetchPolicy
}

Options configures a dispatch run.

type TriggeredHarness

type TriggeredHarness struct {
	Name    string
	Harness *harness.Harness
	Path    string
}

TriggeredHarness pairs a registered agent with its loaded harness.

func FilterAuthorizedHarnesses added in v0.50.0

func FilterAuthorizedHarnesses(harnesses []TriggeredHarness, event *normevent.Event) []TriggeredHarness

FilterAuthorizedHarnesses returns the subset of harnesses that event is authorized to dispatch, keyed on each harness role: field. Run it before MatchHarnesses so CEL only evaluates authorized harnesses.

func FilterAuthorizedHarnessesWith added in v0.54.0

func FilterAuthorizedHarnessesWith(harnesses []TriggeredHarness, event *normevent.Event, opts AuthOptions) []TriggeredHarness

FilterAuthorizedHarnessesWith is FilterAuthorizedHarnesses under the policy in opts.

func ListTriggeredHarnesses

func ListTriggeredHarnesses(ctx context.Context, configDir string, cfg config.ConfigReader, fetchPolicy *fetch.FetchPolicy) ([]TriggeredHarness, error)

ListTriggeredHarnesses returns config-registered agents whose harness has a non-empty trigger. fetchPolicy controls SSRF protection for URL-sourced agents. When nil, fetch.DefaultPolicy is used. Callers that need custom domain lists (e.g. tests using httptest) can pass a policy with the test server's domain.

Per-agent resolve/load failures are logged as GitHub Actions error annotations and skipped so a single broken harness does not block the rest. If every registered agent fails to resolve or load, an error is returned so a fully-unreadable harness set is not indistinguishable from "no trigger matched".

func MatchHarnesses

func MatchHarnesses(candidates []TriggeredHarness, event *normevent.Event) ([]TriggeredHarness, error)

MatchHarnesses evaluates CEL triggers and returns matching harnesses.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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