Add tracker description enrichment worker

Tracker descriptions were only filled on the agent-identification path,
so patterns resolved by domain, sibling, or fallback stayed without one,
and empty mapping upserts could clobber a researched description on the
shared catalog row.

Move description ownership to a dedicated, global common-pattern
enrichment worker. New catalog rows are queued on insert; the worker
researches a compliance-grade description with web search, records it on
the common pattern, and fans it out to every linked tracker pattern. The
mapping worker no longer generates descriptions and only propagates an
already-enriched one at link time.

Rename TrackerMappingConfig to TrackerAgentsConfig since the mapping and
enrichment agents now share it.

Signed-off-by: Émile Ré <emile@probo.com>

pkg/cookiebanner/common_pattern_enrichment_agent.go

@@ -0,0 +1,91 @@
+// Copyright (c) 2026 Probo Inc <hello@getprobo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+package cookiebanner
+
+import (
+	_ "embed"
+	"fmt"
+	"strings"
+
+	"go.gearno.de/kit/log"
+	"go.gearno.de/kit/pg"
+	"go.probo.inc/probo/pkg/agent"
+	"go.probo.inc/probo/pkg/agent/tools/search"
+	"go.probo.inc/probo/pkg/coredata"
+)
+
+//go:embed prompts/tracker_enrichment.txt.tmpl
+var trackerEnrichmentPrompt string
+
+// CommonPatternEnrichmentResult is the structured output the
+// common-pattern enrichment agent returns.
+type CommonPatternEnrichmentResult struct {
+	Description string `json:"description" jsonschema:"A concise, factual, compliance-grade description of what this tracker stores or does and its purpose. One or two sentences. Name the operating company when known."`
+}
+
+func buildCommonPatternEnrichmentAgent(
+	cfg TrackerAgentsConfig,
+	pgClient *pg.Client,
+	logger *log.Logger,
+) *agent.Agent {
+	tools := []agent.Tool{
+		searchThirdPartiesTool(pgClient),
+	}
+
+	if cfg.FirecrawlAPIKey != "" {
+		tools = append(tools, search.FirecrawlSearchTool(cfg.FirecrawlAPIKey))
+	}
+
+	outputType, err := agent.NewOutputType[CommonPatternEnrichmentResult]("tracker_enrichment")
+	if err != nil {
+		panic(fmt.Sprintf("cookiebanner: cannot build tracker enrichment output type: %s", err))
+	}
+
+	return agent.New(
+		"common-pattern-enrichment",
+		cfg.LLMClient,
+		agent.WithInstructions(trackerEnrichmentPrompt),
+		agent.WithModel(cfg.Model),
+		agent.WithTools(tools...),
+		agent.WithOutputType(outputType),
+		agent.WithMaxTurns(agentMaxTurns),
+		agent.WithLogger(logger),
+	)
+}
+
+func buildEnrichmentPrompt(cp coredata.CommonTrackerPattern, thirdPartyName string) string {
+	maxAge := "session"
+	if cp.MaxAgeSeconds != nil {
+		maxAge = fmt.Sprintf("%d seconds", *cp.MaxAgeSeconds)
+	}
+
+	prompt := fmt.Sprintf(
+		"Describe the following tracker:\n\n"+
+			"<pattern> %s </pattern>\n"+
+			"<type> %s </type>\n"+
+			"<match_type> %s </match_type>\n"+
+			"<max_age> %s </max_age>\n",
+		cp.Pattern,
+		cp.TrackerType,
+		cp.MatchType,
+		maxAge,
+	)
+
+	if name := strings.TrimSpace(thirdPartyName); name != "" {
+		prompt += fmt.Sprintf("<third_party> %s </third_party>\n", name)
+	}
+
+	return prompt
+}

pkg/cookiebanner/common_pattern_enrichment_worker.go

@@ -0,0 +1,208 @@
+// Copyright (c) 2026 Probo Inc <hello@getprobo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+package cookiebanner
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"go.gearno.de/kit/log"
+	"go.gearno.de/kit/pg"
+	"go.gearno.de/kit/worker"
+	"go.probo.inc/probo/pkg/agent"
+	"go.probo.inc/probo/pkg/coredata"
+	"go.probo.inc/probo/pkg/llm"
+)
+
+const enrichmentStaleAfter = 10 * time.Minute
+
+type commonPatternEnrichmentHandler struct {
+	pg              *pg.Client
+	logger          *log.Logger
+	enrichmentAgent *agent.Agent
+	staleAfter      time.Duration
+}
+
+// NewCommonPatternEnrichmentWorker builds the worker that fills
+// descriptions on common_tracker_patterns using an agent with web
+// search, then fans the result out to every linked tracker pattern. It is
+// a global system worker: common_tracker_patterns is not tenant-scoped,
+// so a single enrichment benefits all tenants. The worker no-ops when no
+// LLM client is configured; callers should gate registration on config
+// presence.
+func NewCommonPatternEnrichmentWorker(
+	pgClient *pg.Client,
+	logger *log.Logger,
+	cfg TrackerAgentsConfig,
+	opts ...worker.Option,
+) *worker.Worker[coredata.CommonTrackerPattern] {
+	h := &commonPatternEnrichmentHandler{
+		pg:         pgClient,
+		logger:     logger,
+		staleAfter: enrichmentStaleAfter,
+	}
+
+	if cfg.LLMClient != nil {
+		h.enrichmentAgent = buildCommonPatternEnrichmentAgent(cfg, pgClient, logger)
+	}
+
+	return worker.New(
+		"common-pattern-enrichment-worker",
+		h,
+		logger,
+		opts...,
+	)
+}
+
+func (h *commonPatternEnrichmentHandler) Claim(ctx context.Context) (coredata.CommonTrackerPattern, error) {
+	var cp coredata.CommonTrackerPattern
+
+	if err := h.pg.WithTx(
+		ctx,
+		func(ctx context.Context, tx pg.Tx) error {
+			if err := cp.LoadNextForEnrichmentForUpdateSkipLocked(ctx, tx); err != nil {
+				return err
+			}
+
+			return cp.ClearEnrichmentRequestedAt(ctx, tx)
+		},
+	); err != nil {
+		if errors.Is(err, coredata.ErrResourceNotFound) {
+			return coredata.CommonTrackerPattern{}, worker.ErrNoTask
+		}
+
+		return coredata.CommonTrackerPattern{}, fmt.Errorf("cannot claim common tracker pattern enrichment task: %w", err)
+	}
+
+	return cp, nil
+}
+
+func (h *commonPatternEnrichmentHandler) Process(ctx context.Context, cp coredata.CommonTrackerPattern) error {
+	if h.enrichmentAgent == nil {
+		return nil
+	}
+
+	thirdPartyName, err := h.loadThirdPartyName(ctx, cp)
+	if err != nil {
+		return err
+	}
+
+	description, err := h.research(ctx, cp, thirdPartyName)
+	if err != nil {
+		return fmt.Errorf("cannot research tracker description: %w", err)
+	}
+
+	if description == "" {
+		return fmt.Errorf("enrichment produced empty description for pattern %q", cp.Pattern)
+	}
+
+	return h.pg.WithTx(
+		ctx,
+		func(ctx context.Context, tx pg.Tx) error {
+			if err := cp.SetEnriched(ctx, tx, description); err != nil {
+				return fmt.Errorf("cannot set common tracker pattern enriched: %w", err)
+			}
+
+			var patterns coredata.TrackerPatterns
+
+			count, err := patterns.BackfillDescriptionByCommonTrackerPatternID(ctx, tx, cp.ID, description)
+			if err != nil {
+				return err
+			}
+
+			h.logger.InfoCtx(
+				ctx,
+				"enriched common tracker pattern",
+				log.String("common_tracker_pattern_id", cp.ID.String()),
+				log.String("pattern", cp.Pattern),
+				log.Int64("backfilled_tracker_patterns", count),
+			)
+
+			return nil
+		},
+	)
+}
+
+func (h *commonPatternEnrichmentHandler) RecoverStale(ctx context.Context) error {
+	return h.pg.WithConn(
+		ctx,
+		func(ctx context.Context, conn pg.Querier) error {
+			if err := coredata.ResetStaleEnrichments(ctx, conn, h.staleAfter); err != nil {
+				return fmt.Errorf("cannot reset stale common tracker pattern enrichments: %w", err)
+			}
+
+			return nil
+		},
+	)
+}
+
+func (h *commonPatternEnrichmentHandler) loadThirdPartyName(
+	ctx context.Context,
+	cp coredata.CommonTrackerPattern,
+) (string, error) {
+	if cp.CommonThirdPartyID == nil {
+		return "", nil
+	}
+
+	var name string
+
+	if err := h.pg.WithConn(
+		ctx,
+		func(ctx context.Context, conn pg.Querier) error {
+			var party coredata.CommonThirdParty
+			if err := party.LoadByID(ctx, conn, *cp.CommonThirdPartyID); err != nil {
+				return err
+			}
+
+			name = party.Name
+
+			return nil
+		},
+	); err != nil {
+		return "", fmt.Errorf("cannot load common third party for enrichment: %w", err)
+	}
+
+	return name, nil
+}
+
+func (h *commonPatternEnrichmentHandler) research(
+	ctx context.Context,
+	cp coredata.CommonTrackerPattern,
+	thirdPartyName string,
+) (string, error) {
+	prompt := buildEnrichmentPrompt(cp, thirdPartyName)
+
+	agentCtx, cancel := context.WithTimeout(ctx, agentTimeout)
+	defer cancel()
+
+	result, err := agent.RunTyped[CommonPatternEnrichmentResult](
+		agentCtx,
+		h.enrichmentAgent,
+		[]llm.Message{
+			{
+				Role:  llm.RoleUser,
+				Parts: []llm.Part{llm.TextPart{Text: prompt}},
+			},
+		},
+	)
+	if err != nil {
+		return "", fmt.Errorf("enrichment agent run failed: %w", err)
+	}
+
+	return strings.TrimSpace(result.Output.Description), nil
+}

pkg/cookiebanner/prompts/tracker_enrichment.txt.tmpl

@@ -0,0 +1,27 @@
+<role>
+You are a privacy and web-tracking compliance expert. Your job is to write an accurate, source-grounded description of what a given cookie or web tracker does, for use in a privacy/compliance register.
+</role>
+
+<task>
+Given a tracker pattern (cookie name, local storage key, etc.), its type, max-age, and the third party that operates it when known, produce a concise factual description of the tracker's purpose.
+
+Return a structured JSON response with:
+- description: one or two sentences describing what this tracker stores or does and the purpose it serves (e.g. analytics, advertising, session management, security). When the operating company is known, name it.
+</task>
+
+<instructions>
+1. Use the search_third_parties tool to confirm details about the operating company when one is associated with this tracker.
+
+2. Use web_search to find authoritative information about the tracker's purpose. Try up to 3 targeted queries, adapting to the available signals:
+   - With a recognizable prefix or name: "[name] cookie purpose" (e.g. "_ga cookie purpose").
+   - For localStorage keys: "[name] localStorage purpose tracking".
+   - Broaden if needed: "[name] cookie what is it used for".
+   - Stop once you have a confident, well-sourced answer; do not exhaust all queries if the first succeeds.
+   - Verify that any result discusses a tracker whose name shares a meaningful prefix with the pattern being described. Discard results about a differently-named tracker.
+
+3. Be factual and conservative. Describe only what the evidence supports. Do not speculate about data flows or purposes you cannot substantiate.
+
+4. Keep the description concise (one to two sentences) and free of marketing language. It should read as a neutral, compliance-grade statement of purpose.
+
+5. If you genuinely cannot determine the tracker's purpose, write a minimal factual description based on its type and name (e.g. "Cookie set by an unidentified third party; purpose could not be determined.") rather than inventing details.
+</instructions>

pkg/cookiebanner/prompts/tracker_identification.txt.tmpl

@@ -8,7 +8,6 @@ Given a tracker pattern (cookie name, local storage key, etc.), its type, max-ag
 Return a structured JSON response with:
 - third_party_name: the canonical company/service name (e.g. "Google Analytics", not "google" or "GA")
 - category: the business category of the third party
-- description: a one-sentence description of what this tracker does
 - confidence: how confident you are in the identification (0.0 to 1.0)
 </task>
 

pkg/cookiebanner/tracker_agents_config.go

@@ -0,0 +1,28 @@
+// Copyright (c) 2026 Probo Inc <hello@getprobo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+package cookiebanner
+
+import "go.probo.inc/probo/pkg/llm"
+
+// TrackerAgentsConfig configures the tracker agents that share one LLM
+// client, model, and tool surface: the tracker-mapping agent (catalog
+// identification) and the common-pattern enrichment agent (description
+// research). Both use DB-backed search tools and may also use Firecrawl
+// for web search when an API key is supplied.
+type TrackerAgentsConfig struct {
+	LLMClient       *llm.Client
+	Model           string
+	FirecrawlAPIKey string
+}

pkg/cookiebanner/tracker_mapping_agent.go

@@ -26,7 +26,6 @@ import (
 	"go.probo.inc/probo/pkg/agent"
 	"go.probo.inc/probo/pkg/agent/tools/search"
 	"go.probo.inc/probo/pkg/coredata"
-	"go.probo.inc/probo/pkg/llm"
 )
 
 const (
@@ -44,21 +43,11 @@ var trackerIdentificationPrompt string
 type TrackerMappingAgentResult struct {
 	ThirdPartyName string                      `json:"third_party_name" jsonschema:"Name of the company or service that sets this tracker (e.g. 'Google Analytics', 'Meta Pixel'). Empty string if truly unknown."`
 	Category       coredata.ThirdPartyCategory `json:"category" jsonschema:"Third party category"`
-	Description    string                      `json:"description" jsonschema:"What this tracker does in one sentence"`
 	Confidence     float64                     `json:"confidence" jsonschema:"Confidence level from 0.0 to 1.0. Set below 0.5 if unsure."`
 }
 
-// TrackerMappingConfig configures the tracker-mapping agent (catalog
-// identification). The agent uses DB-backed search tools and may also
-// use Firecrawl for web search when an API key is supplied.
-type TrackerMappingConfig struct {
-	LLMClient       *llm.Client
-	Model           string
-	FirecrawlAPIKey string
-}
-
 func buildTrackerMappingAgent(
-	cfg TrackerMappingConfig,
+	cfg TrackerAgentsConfig,
 	pgClient *pg.Client,
 	logger *log.Logger,
 ) *agent.Agent {

pkg/cookiebanner/tracker_mapping_worker.go

@@ -42,7 +42,7 @@ type trackerMappingHandler struct {
 func NewTrackerMappingWorker(
 	pgClient *pg.Client,
 	logger *log.Logger,
-	mappingCfg TrackerMappingConfig,
+	mappingCfg TrackerAgentsConfig,
 	disambiguationCfg thirdparty.DisambiguationConfig,
 	opts ...worker.Option,
 ) *worker.Worker[coredata.TrackerPattern] {
@@ -260,6 +260,11 @@ func (h *trackerMappingHandler) Process(ctx context.Context, tp coredata.Tracker
 				tp.ThirdPartyID = thirdPartyID
 				tp.UpdatedAt = time.Now()
 
+				// Descriptions are owned by the common-pattern enrichment
+				// worker. Here we only propagate: if the linked catalog row
+				// is already enriched, copy its description onto this
+				// pattern. A pattern linked before enrichment is filled
+				// later by the enrichment worker's fan-out instead.
 				if tp.Description == "" && commonPatternID != nil {
 					var commonPattern coredata.CommonTrackerPattern
 					if err := commonPattern.LoadByID(ctx, tx, *commonPatternID); err == nil && commonPattern.Description != "" {
@@ -451,7 +456,6 @@ func (h *trackerMappingHandler) matchByDomain(
 		TrackerType:        tp.TrackerType,
 		Pattern:            tp.Pattern,
 		MatchType:          tp.MatchType,
-		Description:        tp.Description,
 		MaxAgeSeconds:      tp.MaxAgeSeconds,
 		Confidence:         0.7,
 		CreatedAt:          now,
@@ -547,7 +551,6 @@ func (h *trackerMappingHandler) identifyWithAgent(
 		TrackerType:        tp.TrackerType,
 		Pattern:            tp.Pattern,
 		MatchType:          tp.MatchType,
-		Description:        identification.Description,
 		MaxAgeSeconds:      tp.MaxAgeSeconds,
 		Confidence:         confidence,
 		CreatedAt:          now,
@@ -693,7 +696,6 @@ func (h *trackerMappingHandler) matchBySiblingOrigin(
 		TrackerType:        tp.TrackerType,
 		Pattern:            tp.Pattern,
 		MatchType:          tp.MatchType,
-		Description:        tp.Description,
 		MaxAgeSeconds:      tp.MaxAgeSeconds,
 		Confidence:         0.7,
 		CreatedAt:          now,
@@ -822,7 +824,6 @@ func (h *trackerMappingHandler) createUnmatchedPattern(
 		TrackerType:   tp.TrackerType,
 		Pattern:       tp.Pattern,
 		MatchType:     tp.MatchType,
-		Description:   tp.Description,
 		MaxAgeSeconds: tp.MaxAgeSeconds,
 		Confidence:    0.5,
 		CreatedAt:     now,