Documentation
¶
Overview ¶
Package alert implements the native `alert` built-in tool: a config-driven, distroless-safe way for a headless core-agent daemon to fire escalations to pre-registered webhook targets (Slack, Discord, PagerDuty, generic JSON) without shelling out or running a separate MCP server. The design lives in docs/alert-tool-design.md.
SSRF is impossible by construction: the tool exposes no arbitrary-URL parameter — the model picks a target by NAME from the operator's registry, and an unknown name is rejected rather than dialed.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrRateLimited = fmt.Errorf("alert: rate-limited")
ErrRateLimited is returned by Send when the target's budget for this window is spent. A sentinel so a caller can log it differently from a delivery failure — the destination is fine, we chose not to call it.
Functions ¶
func HasLiveTarget ¶
HasLiveTarget reports whether any configured target can be delivered to. pkg/tools.Build uses it as the second half of `alert`'s registration gate, so a build whose every target is unresolvable registers no alert tool at all rather than one that cannot fire.
Types ¶
type Args ¶
type Args struct {
Target string `` /* 150-byte string literal not displayed */
Level string `json:"level" jsonschema:"required; severity of the alert: one of info, warning, critical, resolved"`
Summary string `json:"summary" jsonschema:"required; a one-line human-readable summary of what happened"`
Details map[string]any `` /* 158-byte string literal not displayed */
}
Args is the tool's input. Auth material is deliberately absent — it is resolved from env at call time and never appears in the schema or the audited args (design §Security).
type DeadTarget ¶
DeadTarget is a configured target this process cannot deliver to, paired with the operator-facing reason.
func PartitionTargets ¶
func PartitionTargets(cfg *config.Config) (live []config.AlertTarget, dead []DeadTarget)
PartitionTargets splits cfg's registry into the targets this process can actually fire and those it cannot.
A target whose url_env (or auth env) is unset can never deliver: a process's environment is fixed at exec time, so "unset now" means "unset for this process's whole life" — a Secret edit needs a pod restart either way. Registering it anyway hands the model an escalation path that fails at the one moment it is needed. A live 2026-08-14 run called `alert` at the end of an incident it could not resolve and learned only then that nobody had been paged; the target had been advertised in the tool description all along.
Same rule as the built-in descriptions (#759), one layer down: never name a capability the deployment doesn't have.
type Result ¶
type Result struct {
Target string `json:"target"`
StatusCode int `json:"status_code"`
DurationMs int64 `json:"duration_ms"`
}
Result is the tool's output. Response BODY is intentionally excluded — it may carry PII from the destination and could be a smuggle channel back to the model; only the status code and duration are returned.
type Sender ¶
type Sender struct {
// contains filtered or unexported fields
}
Sender delivers to ONE pre-registered alert target on behalf of the runtime itself rather than on behalf of the model.
Three differences from the `alert` tool, and each of them is the reason this type exists instead of a second caller of the tool:
It is not gated. The permission gate decides what the MODEL may do; a notification the gate emits about its own unanswered prompt is not a model action, and routing it through the gate would be circular — the gate asking permission to tell you it needs permission, with nobody attached to answer either one.
It carries its own rate-limit budget. The tool's limiter is keyed per target and shared across every call the model makes; if the runtime drew from the same bucket, a chatty agent could exhaust it and silence the channel that governs that same agent. A dropped model alert is a dropped alert. A dropped approval notification is an operator who never learns their gate is waiting.
Its target is fixed at construction. The model picks a target by name; the runtime was told which one to use by the operator, and resolving a name per call would be a lookup that can start failing long after startup said it would work.
Construction fails when the named target is unknown or undeliverable, which is deliberate: a caller that wants out-of-band notification and cannot have it must find out at wiring time, not at the first prompt nobody answers.
func (*Sender) Send ¶
func (s *Sender) Send(ctx context.Context, level, summary string, details map[string]any, session string) error
Send delivers one notification. level must be one of the values the tool accepts; session is interpolated by templates that reference it and may be empty.
A rate-limited send returns ErrRateLimited rather than nil. Reporting it as a success would be the same lie the whole out-of-band path exists to prevent: the caller believes somebody was told.