alert

package
v3.1.0-dev.1 Latest Latest
Warning

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

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

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

View Source
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

func HasLiveTarget(cfg *config.Config) bool

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.

func New

func New(gate *permissions.Gate, cfg *config.Config) (tool.Tool, error)

New builds the alert tool from cfg's target registry, keeping only the targets this process can actually deliver to (see PartitionTargets). The caller (pkg/tools.Build) gates registration on HasLiveTarget, so the model never sees an `alert` with no reachable destinations.

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

type DeadTarget struct {
	Name   string
	Reason string
}

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 NewSender

func NewSender(cfg *config.Config, target string) (*Sender, error)

NewSender builds a Sender for the target named in cfg's registry.

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.

func (*Sender) Target

func (s *Sender) Target() string

Target reports the name this Sender delivers to, for startup logs that want to say where notifications will go.

Jump to

Keyboard shortcuts

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