tools

type ChangeFeed ¶

type ChangeFeed interface {
	// Changes returns every change record at or after `since`. A missing
	// or empty feed yields an empty slice and a nil error (a clean miss,
	// never a hard failure).
	Changes(ctx context.Context, since time.Time) ([]ChangeRecord, error)
}

ChangeFeed is the read-only feed of recent changes the recent_changes tool reads from. It is declared as a local interface so the tools package stays decoupled from config and pkg/agent.

func NewGitChangeFeed(repos []GitRepo) ChangeFeed

type ChangeRecord ¶

type ChangeRecord struct {
	Timestamp time.Time `json:"timestamp"`
	Service   string    `json:"service"`
	Kind      string    `json:"kind"`
	Summary   string    `json:"summary"`
	Ref       string    `json:"ref,omitempty"`
}

ChangeRecord is one change derived from a git commit: a deploy, config change, or feature-flag flip recorded in the repository's history.

type DependencyGraph ¶

type DependencyGraph struct {
	// contains filtered or unexported fields
}

DependencyGraph is the read-only service-dependency graph that powers the describe_dependencies tool. It is built from the operator-authored `depends_on` (upstream) edges; the reverse `depended_on_by` (downstream) edges are derived automatically. The graph is immutable after construction.

func NewDependencyGraph(dependsOn map[string][]string) *DependencyGraph

func (g *DependencyGraph) Len() int

func (g *DependencyGraph) Topology(maxNodes, maxEdges int) core.ServiceTopology

type DescribeBaseline ¶ added in v1.4.27

type DescribeBaseline struct {
	Provider core.BaselineProvider
	OrgID    string
	Now      func() time.Time
}

DescribeBaseline reads learned expectations from a trusted scoped provider.

func (DescribeBaseline) ArgsSchema() map[string]any

func (tool DescribeBaseline) AvailabilityCapability() (string, string, int)

func (DescribeBaseline) Description() string

func (DescribeBaseline) DisplayName() string

func (tool DescribeBaseline) Invoke(ctx context.Context, raw json.RawMessage) (*core.ToolResult, error)

func (DescribeBaseline) Name() string

type DescribeDependencies ¶

type DescribeDependencies struct {
	Graph *DependencyGraph
	// Store is optional. When nil, neighbours are returned without the
	// has_recent_incident annotation.
	Store storage.Provider
	// Scope is the ordered organization read scope. Its zero value is the
	// default-only OSS view.
	Scope tenancy.OrgScope
}

DescribeDependencies surfaces the upstream and downstream neighbours of a service from the operator-authored dependency graph, each annotated with whether that neighbour also has a recent incident. The agent uses it to reason about cascading failures.

func (DescribeDependencies) ArgsSchema() map[string]any

func (DescribeDependencies) Description() string

func (DescribeDependencies) DisplayName() string

func (d DescribeDependencies) Invoke(_ context.Context, args json.RawMessage) (*core.ToolResult, error)

func (DescribeDependencies) Name() string

type FindRunbook ¶

type FindRunbook struct {
	Embedder core.Embedder
	Index    RunbookSearcher
	Redactor LineRedactor
}

FindRunbook is the read-only runbook-RAG tool. During an investigation it embeds a redacted query derived from the incident, runs a top-K similarity search over the operator-supplied runbook corpus, and returns the best-matching excerpts so the model can ground its finding in the team's own remediation docs. It performs NO writes, NO ingestion, NO on-call trigger, and NO notification — it is search-only.

The query MUST be scrubbed through the redactor before it reaches the embedder: the embeddings call is the same external trust boundary as the chat-completion call, so incident-derived text never egresses raw.

func (FindRunbook) ArgsSchema() map[string]any

func (FindRunbook) Description() string

func (FindRunbook) DisplayName() string

func (fr FindRunbook) Invoke(ctx context.Context, args json.RawMessage) (*core.ToolResult, error)

func (FindRunbook) Name() string

type GitRepo ¶

type GitRepo struct {
	// URL is the remote clone URL (https or scp-like git@host:org/repo).
	URL string
	// Branch optionally pins which branch to read; empty = default HEAD.
	Branch string
	// Service maps every commit in this repository to a service name.
	// Empty derives the service from the repository name in the URL.
	Service string
	// Token is an HTTPS access token / PAT used to authenticate to the
	// remote. Empty relies on ambient credentials.
	Token string
	// SSHKeyPath is the path to a private SSH key used for ssh / scp-like
	// remotes. Empty relies on the ambient SSH configuration.
	SSHKeyPath string
}

GitRepo describes one remote git repository the change feed reads.

type LineRedactor ¶

type LineRedactor interface {
	Scrub(s string) string
}

LineRedactor scrubs sensitive substrings before they reach a model.

type RecentChanges ¶

type RecentChanges struct {
	Feed ChangeFeed
}

RecentChanges surfaces recent deploys, config changes, and feature-flag flips so Chat and Analyze can correlate an incident with what changed just before it. It is strictly read-only.

func (RecentChanges) ArgsSchema() map[string]any

func (RecentChanges) Description() string

func (RecentChanges) DisplayName() string

func (rc RecentChanges) Invoke(ctx context.Context, args json.RawMessage) (*core.ToolResult, error)

func (RecentChanges) Name() string

type RelatedLogs ¶

type RelatedLogs struct {
	Reader   SignalReader
	Redactor LineRedactor
	Services ServiceExtractor
}

RelatedLogs pulls a raw-log slice from the configured signal sources around the incident window so the analyze agent can inspect the surrounding context. Every returned line is scrubbed through the same redactor used before any AI call, so secrets never reach the model.

func (RelatedLogs) ArgsSchema() map[string]any

func (RelatedLogs) Description() string

func (RelatedLogs) DisplayName() string

func (rl RelatedLogs) Invoke(ctx context.Context, args json.RawMessage) (*core.ToolResult, error)

func (RelatedLogs) Name() string

type RunbookMatch ¶

type RunbookMatch struct {
	ID      string  `json:"id"`
	Title   string  `json:"title"`
	Service string  `json:"service,omitempty"`
	Score   float32 `json:"score"`
	Excerpt string  `json:"excerpt,omitempty"`
	Source  string  `json:"source,omitempty"`
}

RunbookMatch is one runbook hit returned to the model. It is the tools-package mirror of the vector index's result so the tool stays decoupled from pkg/runbook (the write path): the bridge in pkg/agent/analyze_adapter.go converts the concrete index results into this shape, keeping the import graph one-directional and the read-only guard green.

type RunbookSearcher ¶

type RunbookSearcher interface {
	Search(ctx context.Context, query []float32, service string, limit int) ([]RunbookMatch, error)
}

RunbookSearcher is the read-only vector-search seam the find_runbook tool depends on. Declared as a local interface (not an import of pkg/runbook) so the tools package never pulls in the ingestion/write path — the import-graph guard enforces this. Search takes an already embedded query vector, an optional service filter, and a result cap.

type ServiceExtractor ¶

type ServiceExtractor interface {
	Extract(message string) string
}

ServiceExtractor extracts an operator-configured service name from a message.

type SignalReader ¶

type SignalReader interface {
	Sources() []string
	Pull(ctx context.Context, source string, since time.Time) ([]core.Signal, error)
}

SignalReader is the read-only slice of configured signal sources used by tools.