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

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 MetricReader ¶

type MetricReader interface {
	// QueryRange runs a PromQL range query over the absolute interval
	// and returns the matching series. An empty result is a clean miss,
	// not an error.
	QueryRange(ctx context.Context, query string, start, end time.Time) ([]MetricSeries, error)
}

MetricReader is the read-only slice of a metric backend the query_metrics tool depends on. Declared as a local interface (not importing pkg/signalsources) to keep the import graph one-directional. The bridge in pkg/agent wraps a Prometheus querier so an on-demand analyze query never touches the detect-path source cursors.

type MetricSample ¶

type MetricSample struct {
	Timestamp time.Time
	Value     float64
}

MetricSample is one (timestamp, value) point of a metric series, declared locally so the tools package stays decoupled from pkg/signalsources and pkg/agent (a bridge converts the concrete types). Mirrors signalsources.MetricSample.

type MetricSeries ¶

type MetricSeries struct {
	Labels  map[string]string
	Samples []MetricSample
}

MetricSeries is one labelled series returned by the MetricReader.

type QueryMetrics ¶

type QueryMetrics struct {
	Reader MetricReader
}

QueryMetrics runs an on-demand PromQL range query against the configured metric backend so the analyze agent can inspect a metric's recent behaviour. It is strictly read-only.

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

func (QueryMetrics) Description() string

func (QueryMetrics) DisplayName() string

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

func (QueryMetrics) Name() string

type QueryTraces ¶

type QueryTraces struct {
	Reader   TraceReader
	Redactor LineRedactor
}

QueryTraces searches the configured trace backend for recent error / latency-outlier traces so the analyze agent can correlate an incident with distributed-tracing evidence. It is strictly read-only and scrubs every service/operation string through the redactor before returning.

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

func (QueryTraces) Description() string

func (QueryTraces) DisplayName() string

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

func (QueryTraces) Name() string

type RecentChanges ¶

type RecentChanges struct {
	Feed ChangeFeed
}

RecentChanges surfaces recent deploys, config changes, and feature-flag flips so the analyze agent 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.

type TraceReader ¶

type TraceReader interface {
	// QueryTraces searches the backend over the absolute interval,
	// optionally narrowing by service and/or trace_id, and returns up to
	// `limit` summaries. An empty result is a clean miss, not an error.
	QueryTraces(ctx context.Context, service, traceID string, start, end time.Time, limit int) ([]TraceSummary, error)
}

TraceReader is the read-only slice of a trace backend the query_traces tool depends on. Declared as a local interface (not importing pkg/signalsources) to keep the import graph one-directional. The bridge in pkg/agent wraps a Tempo querier so an on-demand analyze search never touches the detect-path source cursors.

type TraceSummary ¶

type TraceSummary struct {
	TraceID    string
	Service    string
	Operation  string
	DurationMs float64
	Start      time.Time
	Error      bool
}

TraceSummary is one trace returned by the TraceReader, flattened to the fields the analyze agent reasons over. Declared locally so the tools package stays decoupled from pkg/signalsources; a bridge in pkg/agent converts the concrete signalsources.TraceSummary.