Documentation
¶
Overview ¶
Package gatereason reads the gate-reason record of a call (docs/design/untrusted-content-and-amount- caps.md, sections 5.3 and 7) into the reasons an approver, a notifier and a viewer are shown: why the call needs a gate beyond its tool's own. A reason is evidence and the application's claim, never authority: nothing read here decides a gate, and the signed decision does not bind it. The package imports no other bide package that imports the agent, so the agent's notifier payload can carry its type.
Index ¶
Constants ¶
const ( // KindTaint: the requesting turn had read untrusted content. KindTaint = "taint" // KindCap: a cap rule applies. KindCap = "cap" // KindConflict: two records name the call and disagree, so none is shown (see Find). KindConflict = "conflict" )
Reason kinds.
const MaxText = 128
MaxText bounds every host-declared string of a reason, which is shown to people.
const Prefix = "gate-reason:"
Prefix is the name prefix of a gate-reason record, reserved to the engine.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Reason ¶
type Reason struct {
// Kind is KindTaint or KindCap.
Kind string `json:"kind"`
// Source and Ref (taint): the declared source of the content, and where it was read: "tool:<name>/<call>",
// "input" or "retrieval". Pos is the position of the mark in the run's journal.
Source string `json:"source,omitempty"`
Ref string `json:"ref,omitempty"`
Pos int `json:"pos,omitempty"`
// Rule, Action, Why, Currency, Amount and Limit (cap): the rule's name, what it decided ("gate" or
// "refuse"), why it fired ("over", "not_assessable" or "currency"), and this call's amount and the
// rule's limit in minor units of Currency. Amount is nil when the call's amount could not be assessed.
Rule string `json:"rule,omitempty"`
Action string `json:"action,omitempty"`
Why string `json:"why,omitempty"`
Currency string `json:"currency,omitempty"`
Amount *int64 `json:"amount,omitempty"`
Limit int64 `json:"limit,omitempty"`
// At is when the engine recorded the reason (the ask), by the run's clock: the figures are as of then.
At string `json:"at,omitempty"`
}
Reason is one reason a call is gated, as the record holds it. Every string is a host-declared name (a source, a tool and call, a rule), cut to MaxText bytes and escaped when it is not printable text, so it can be shown as it is.
func Find ¶
Find is the reasons for the gate instance subject: for the escalation instance of a call ("<call>#taint"), the taint reasons of the call's record; for the call's own gate, its cap reasons. It returns none when the run has no record for the call, or none that reads.
Every record that names the call and reads must agree: a record under another name that names the call (a decoy written ahead of the engine's, or behind it) is not told from the engine's by its position, so when two disagree no reason is shown, and a single reason of Kind KindConflict stands in its place, so the approver sees that something is wrong. Records that say the same are one.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package agentrecs adapts a run's records to gatereason.Records, for the packages that read a journal through the agent package (the approvals intake, the run viewer, the audit CLI).
|
Package agentrecs adapts a run's records to gatereason.Records, for the packages that read a journal through the agent package (the approvals intake, the run viewer, the audit CLI). |