154 lines
4.1 KiB
Go
154 lines
4.1 KiB
Go
// Package guard is what a Go guard extension builds on: the generated
|
|
// guard.v1 contract, the interface a guard implements and the Serve helper
|
|
// archie-core launches it with.
|
|
package guard
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json/jsontext"
|
|
"time"
|
|
)
|
|
|
|
// Contract is the guard contract version this SDK speaks.
|
|
const Contract = "v1"
|
|
|
|
// Ceiling is the five-level scale a guard answers with, from the most
|
|
// autonomy to the least. The action runs at the lowest ceiling any guard sets.
|
|
type Ceiling int
|
|
|
|
// The five levels. The zero Ceiling means the guard gave none, which holds the
|
|
// action at propose and wait.
|
|
const (
|
|
ActQuietly Ceiling = iota + 1
|
|
ActAndTell
|
|
ProposeAndWait
|
|
Escalate
|
|
Never
|
|
)
|
|
|
|
// Strength is how much a finding's evidence supports it.
|
|
type Strength int
|
|
|
|
// Evidence strengths.
|
|
const (
|
|
StrengthUnspecified Strength = iota
|
|
Weak
|
|
Moderate
|
|
Strong
|
|
)
|
|
|
|
// Config is the operator's settings and the host-resolved secrets.
|
|
type Config struct {
|
|
Settings map[string]string
|
|
Secrets map[string]string
|
|
}
|
|
|
|
// Description names the guard and says whether its verdicts count.
|
|
type Description struct {
|
|
Name string
|
|
Version string
|
|
// Advisory verdicts are recorded and set no ceiling.
|
|
Advisory bool
|
|
}
|
|
|
|
// Action is one concrete action put to the guard.
|
|
type Action struct {
|
|
Connector string
|
|
Name string
|
|
Input jsontext.Value
|
|
Digest string
|
|
Target Target
|
|
Effect Effect
|
|
RunID string
|
|
// DecisionKey identifies the attempt to run the action.
|
|
DecisionKey string
|
|
// Deadline is how long the host waits for the verdict.
|
|
Deadline time.Duration
|
|
// At is the host's clock when the action was put to the guard.
|
|
At time.Time
|
|
// Diagnosis is what the proposing agent concluded so far, in its own
|
|
// words. Empty when no agent proposed the action.
|
|
Diagnosis string
|
|
// Evidence is what the agent read during the run, oldest first.
|
|
Evidence []Evidence
|
|
}
|
|
|
|
// Evidence is one result the agent read, as the tool returned it.
|
|
type Evidence struct {
|
|
Source string
|
|
Text string
|
|
}
|
|
|
|
// Target is what the action acts on.
|
|
type Target struct {
|
|
Kind string
|
|
ID string
|
|
Environment string
|
|
Disposable bool
|
|
}
|
|
|
|
// Effect is what the connector says the action does.
|
|
type Effect struct {
|
|
ReadOnly bool
|
|
// Reversibility is 1 (undone automatically), 2 (recoverable), 3
|
|
// (irreversible), or 0 when the connector declared none.
|
|
Reversibility int
|
|
Summary string
|
|
}
|
|
|
|
// Finding is one thing the guard noticed, with what it rests on.
|
|
type Finding struct {
|
|
Text string
|
|
Evidence string
|
|
Strength Strength
|
|
}
|
|
|
|
// Verdict is a guard's judgement of one action. A guard with no concern
|
|
// returns Ceiling ActQuietly and no findings.
|
|
type Verdict struct {
|
|
Ceiling Ceiling
|
|
Findings []Finding
|
|
BlindSpots []string
|
|
// Judges is every model judgement the verdict rests on, clean answers
|
|
// included, so the verdict can be audited without asking the model again.
|
|
Judges []JudgeRecord
|
|
}
|
|
|
|
// JudgeRecord is what one model judge answered and what it was judged on.
|
|
type JudgeRecord struct {
|
|
Model string
|
|
// ResultID identifies the judge's result with the service that ran it.
|
|
ResultID string
|
|
Answer string
|
|
Confidence float64
|
|
// Reason is the judge's reasoning, or why the call failed.
|
|
Reason string
|
|
// Basis is the text the judge was given beyond the action, such as the
|
|
// policy rules, and BasisDigest its SHA-256 in hex.
|
|
Basis string
|
|
BasisDigest string
|
|
// Answers is every answer as JSON: choice, probabilities and confidence.
|
|
Answers []byte
|
|
// Trusted says the judge has passed its recorded eval. When it hasn't,
|
|
// AdvisoryReason says why.
|
|
Trusted bool
|
|
AdvisoryReason string
|
|
// EvalDate is the day of the eval the judge's standing comes from.
|
|
EvalDate string
|
|
// Request and Response are the exact bodies the judge endpoint was sent
|
|
// and returned, kept even when the call failed.
|
|
Request []byte
|
|
Response []byte
|
|
EndpointPath string
|
|
HTTPStatus int
|
|
LatencyMS int64
|
|
}
|
|
|
|
// Guard judges one concrete action.
|
|
type Guard interface {
|
|
Describe() Description
|
|
// Judge returns the verdict. An error holds the action at propose and
|
|
// wait, unless the guard is advisory.
|
|
Judge(ctx context.Context, a Action) (Verdict, error)
|
|
}
|