From 2ce1439eebe518361691f8925503908c30937921 Mon Sep 17 00:00:00 2001
From: Hung Nguyen <hungit.khtn06@gmail.com>
Date: Tue, 3 Nov 2026 18:20:29 +0700
Subject: [PATCH 1/5] feat(otelsetup): one-call Providers.Instrument; fix
 scheme-less env endpoint

- tel.Instrument(loop) wires loop, LLM and every registered tool; no-op when
  telemetry is off, idempotent (otelllm/oteltools skip already-wrapped).
- tools.Registry.Use wraps an already-populated registry.
- Fix: OTEL_EXPORTER_OTLP_ENDPOINT=host:port (no scheme) failed every export
  with an empty host; it is now passed to the exporter as host:port.
- Chat span is named "chat" when the model is unknown.
---
 docs/observability.md                      |  22 ++++
 pkg/telemetry/otelllm/provider.go          |  10 +-
 pkg/telemetry/otelsetup/instrument.go      |  37 ++++++
 pkg/telemetry/otelsetup/instrument_test.go | 125 +++++++++++++++++++++
 pkg/telemetry/otelsetup/resolve.go         |  23 +++-
 pkg/telemetry/otelsetup/setup.go           |  26 +++--
 pkg/telemetry/otelsetup/setup_test.go      |   9 +-
 pkg/telemetry/oteltools/middleware.go      |   3 +
 pkg/tools/registry_use_test.go             |  56 +++++++++
 pkg/tools/tool.go                          |  19 ++++
 10 files changed, 314 insertions(+), 16 deletions(-)
 create mode 100644 pkg/telemetry/otelsetup/instrument.go
 create mode 100644 pkg/telemetry/otelsetup/instrument_test.go
 create mode 100644 pkg/tools/registry_use_test.go

diff --git a/docs/observability.md b/docs/observability.md
index 5139e3a..27223da 100644
--- a/docs/observability.md
+++ b/docs/observability.md
@@ -59,6 +59,28 @@ if err != nil { /* ... */ }
 defer shutdown(context.Background())
 ```
 
+### The short way: one call
+
+```go
+tel, shutdown, err := otelsetup.Setup(ctx, otelsetup.Config{ServiceName: "my-agent"})
+if err != nil { /* invalid OTEL_* configuration */ }
+defer shutdown(context.Background())
+
+tel.Instrument(loop, otelllm.WithSystem("anthropic"), otelllm.WithModel(model))
+```
+
+`Instrument` wires the loop (run/iteration spans, run metrics), its LLM (chat
+spans, token metrics), and every registered tool (execute_tool spans) — for a
+loop from `agent.New` or the YAML builder alike. Call it after the tools are
+registered; calling it twice is harmless. With no endpoint configured it does
+nothing, so call it unconditionally and enable telemetry purely with env:
+
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317   # host:port or http://host:4317
+```
+
+The sections below show the same wiring piece by piece, for finer control.
+
 ### Loops built with `agent.New`
 
 ```go
diff --git a/pkg/telemetry/otelllm/provider.go b/pkg/telemetry/otelllm/provider.go
index f106a02..4abdbeb 100644
--- a/pkg/telemetry/otelllm/provider.go
+++ b/pkg/telemetry/otelllm/provider.go
@@ -95,6 +95,10 @@ func NewProvider(next agent.LLMProvider, opts ...Option) agent.LLMProvider {
 	if cfg.tracer == nil && cfg.meter == nil {
 		return next
 	}
+	switch next.(type) {
+	case *instrumentedProvider, *capableProvider:
+		return next // already instrumented: wrapping again would double every span
+	}
 	capture := semconv.CaptureContentFromEnv()
 	if cfg.capture != nil {
 		capture = *cfg.capture
@@ -237,7 +241,11 @@ func (p *instrumentedProvider) startSpan(ctx context.Context) (context.Context,
 	if p.tracer == nil {
 		return ctx, nil
 	}
-	return p.tracer.Start(ctx, "chat "+p.model,
+	name := semconv.OperationChat
+	if p.model != "" {
+		name += " " + p.model
+	}
+	return p.tracer.Start(ctx, name,
 		trace.WithSpanKind(trace.SpanKindClient),
 		trace.WithAttributes(p.spanAttrs...),
 	)
diff --git a/pkg/telemetry/otelsetup/instrument.go b/pkg/telemetry/otelsetup/instrument.go
new file mode 100644
index 0000000..24ec992
--- /dev/null
+++ b/pkg/telemetry/otelsetup/instrument.go
@@ -0,0 +1,37 @@
+package otelsetup
+
+import (
+	"github.com/hung12ct/gopheragent/pkg/agent"
+	"github.com/hung12ct/gopheragent/pkg/telemetry/otelllm"
+	"github.com/hung12ct/gopheragent/pkg/telemetry/oteltools"
+)
+
+// Instrument wires full tracing and metrics into an already-built loop in one
+// call: run and iteration spans on the loop, a chat span plus token metrics
+// around loop.LLM, and an execute_tool span plus latency on every tool in
+// loop.Tools. Pass otelllm options to label the model, e.g.
+//
+//	tel.Instrument(loop, otelllm.WithSystem("anthropic"), otelllm.WithModel(model))
+//
+// Call it once the loop is configured and its tools are registered; tools
+// registered later are not instrumented. Calling it twice is harmless. When
+// telemetry is disabled (no endpoint configured) it changes nothing, so it is
+// safe to call unconditionally. Returns loop for chaining.
+//
+// Sub-agent tools (builtin.CallSubAgentTool) hold their own LLM: wrap it with
+// otelllm.NewProvider when constructing the tool to get the worker's chat
+// spans. Worker run spans and metrics are inherited automatically.
+func (p *Providers) Instrument(loop *agent.AgentLoop, llmOpts ...otelllm.Option) *agent.AgentLoop {
+	if p == nil || !p.Enabled || loop == nil {
+		return loop
+	}
+	loop.Configure(agent.WithTracer(p.Tracer), agent.WithMeter(p.Meter))
+	if loop.LLM != nil {
+		opts := append([]otelllm.Option{otelllm.WithTracer(p.Tracer), otelllm.WithMeter(p.Meter)}, llmOpts...)
+		loop.LLM = otelllm.NewProvider(loop.LLM, opts...)
+	}
+	if loop.Tools != nil {
+		loop.Tools.Use(oteltools.Instrument(oteltools.WithTracer(p.Tracer), oteltools.WithMeter(p.Meter)))
+	}
+	return loop
+}
diff --git a/pkg/telemetry/otelsetup/instrument_test.go b/pkg/telemetry/otelsetup/instrument_test.go
new file mode 100644
index 0000000..f7a032e
--- /dev/null
+++ b/pkg/telemetry/otelsetup/instrument_test.go
@@ -0,0 +1,125 @@
+package otelsetup_test
+
+import (
+	"context"
+	"fmt"
+	"testing"
+
+	"go.opentelemetry.io/otel"
+
+	"github.com/hung12ct/gopheragent/pkg/agent"
+	"github.com/hung12ct/gopheragent/pkg/history"
+	"github.com/hung12ct/gopheragent/pkg/telemetry/otelllm"
+	"github.com/hung12ct/gopheragent/pkg/telemetry/otelsetup"
+	"github.com/hung12ct/gopheragent/pkg/tools"
+)
+
+// echoLoop builds an uninstrumented loop whose LLM calls echo once, then answers.
+func echoLoop() *agent.AgentLoop {
+	reg := tools.NewRegistry()
+	tools.RegisterFunc(reg, "echo", "echo text", func(_ context.Context, a echoArgs) (tools.Result, error) {
+		return tools.Text(a.Text), nil
+	})
+	return agent.New(history.NewInMemSessionManager("sys"), reg, &onceToolLLM{})
+}
+
+type onceToolLLM struct{ called bool }
+
+func (o *onceToolLLM) GenerateStream(context.Context, []history.Message, *tools.Registry, chan<- agent.StreamEvent) (agent.LLMResult, error) {
+	if o.called {
+		return agent.LLMResult{Content: "done"}, nil
+	}
+	o.called = true
+	return agent.LLMResult{ToolCalls: []agent.PendingToolCall{{ID: "c1", Name: "echo", ArgsJSON: `{"text":"hi"}`}}}, nil
+}
+
+func TestInstrument_DisabledChangesNothing(t *testing.T) {
+	clearOTelEnv(t)
+	tel, shutdown, err := otelsetup.Setup(context.Background(), otelsetup.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = shutdown(context.Background()) }()
+	loop := echoLoop()
+	llm := loop.LLM
+	echo, _ := loop.Tools.Get("echo")
+	if tel.Instrument(loop) != loop || loop.LLM != llm {
+		t.Fatal("disabled Instrument must leave the loop's LLM untouched")
+	}
+	if after, _ := loop.Tools.Get("echo"); after != echo {
+		t.Fatal("disabled Instrument must leave tools unwrapped")
+	}
+	var nilProviders *otelsetup.Providers
+	if nilProviders.Instrument(loop) != loop {
+		t.Fatal("nil Providers must be a no-op")
+	}
+}
+
+// TestInstrument_OneCallMatchesManualWiring: one Instrument call (twice, to
+// prove idempotence) yields the full run → iteration → chat → execute_tool
+// tree over real OTLP, each span exactly once.
+func TestInstrument_OneCallMatchesManualWiring(t *testing.T) {
+	clearOTelEnv(t)
+	prevTP, prevMP, prevProp := otel.GetTracerProvider(), otel.GetMeterProvider(), otel.GetTextMapPropagator()
+	t.Cleanup(func() {
+		otel.SetTracerProvider(prevTP)
+		otel.SetMeterProvider(prevMP)
+		otel.SetTextMapPropagator(prevProp)
+	})
+	r := &receiver{}
+	tel, shutdown, err := otelsetup.Setup(context.Background(), otelsetup.Config{ServiceName: "e2e", Endpoint: startGRPC(t, r), Insecure: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	loop := echoLoop()
+	tel.Instrument(loop, otelllm.WithSystem("fake"), otelllm.WithModel("m"))
+	tel.Instrument(loop, otelllm.WithSystem("fake"), otelllm.WithModel("m"))
+
+	if _, err := loop.RunIteration(context.Background(), "s", "go"); err != nil {
+		t.Fatal(err)
+	}
+	if err := shutdown(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	counts := map[string]int{}
+	for _, s := range r.spans {
+		counts[s.GetName()]++
+	}
+	want := map[string]int{"agent.run": 1, "agent.iteration": 2, "chat m": 2, "execute_tool echo": 1}
+	for name, n := range want {
+		if counts[name] != n {
+			t.Fatalf("span %q x%d, want x%d (all: %v)", name, counts[name], n, counts)
+		}
+	}
+	if len(r.metrics) == 0 {
+		t.Fatal("no metrics exported")
+	}
+}
+
+// TestSetup_EnvOnlyEndpointExports covers the env-only path both ways an
+// operator writes it: "host:port" (which the exporter alone can't parse) and
+// a URL.
+func TestSetup_EnvOnlyEndpointExports(t *testing.T) {
+	for _, form := range []string{"%s", "http://%s"} {
+		t.Run(form, func(t *testing.T) {
+			clearOTelEnv(t)
+			prevTP, prevMP := otel.GetTracerProvider(), otel.GetMeterProvider()
+			t.Cleanup(func() { otel.SetTracerProvider(prevTP); otel.SetMeterProvider(prevMP) })
+			r := &receiver{}
+			t.Setenv("OTEL_EXPORTER_OTLP_ENDPOINT", fmt.Sprintf(form, startGRPC(t, r)))
+			t.Setenv("OTEL_EXPORTER_OTLP_INSECURE", "true")
+			tel, shutdown, err := otelsetup.Setup(context.Background(), otelsetup.Config{ServiceName: "e2e"})
+			if err != nil {
+				t.Fatal(err)
+			}
+			loop := tel.Instrument(echoLoop())
+			_, _ = loop.RunIteration(context.Background(), "s", "go")
+			if err := shutdown(context.Background()); err != nil {
+				t.Fatalf("export with env endpoint %q failed: %v", form, err)
+			}
+			if len(r.spans) == 0 {
+				t.Fatalf("no spans exported with OTEL_EXPORTER_OTLP_ENDPOINT in form %q", form)
+			}
+		})
+	}
+}
diff --git a/pkg/telemetry/otelsetup/resolve.go b/pkg/telemetry/otelsetup/resolve.go
index 057a6e1..6b41fe7 100644
--- a/pkg/telemetry/otelsetup/resolve.go
+++ b/pkg/telemetry/otelsetup/resolve.go
@@ -25,6 +25,10 @@ const (
 type signalPlan struct {
 	enabled  bool
 	protocol string
+	// endpoint is a host:port passed to the exporter explicitly: Config.Endpoint,
+	// or an env endpoint written without a scheme. Empty: the exporter reads
+	// its (URL-form) env var itself.
+	endpoint string
 }
 
 // resolveSignal decides, once at Setup time, whether a signal exports and over
@@ -59,7 +63,7 @@ func resolveSignal(cfg Config, getenv func(string) string, kind signalKind) (sig
 		return signalPlan{}, fmt.Errorf("otelsetup: unsupported OTLP protocol %q for %s (want %s or %s)",
 			proto, strings.ToLower(string(kind)), ProtocolGRPC, ProtocolHTTP)
 	}
-	return signalPlan{enabled: true, protocol: proto}, nil
+	return signalPlan{enabled: true, protocol: proto, endpoint: explicitEndpoint(cfg, getenv, kind)}, nil
 }
 
 func firstNonEmpty(vals ...string) string {
@@ -70,3 +74,20 @@ func firstNonEmpty(vals ...string) string {
 	}
 	return ""
 }
+
+// explicitEndpoint returns the endpoint to pass as host:port. The OTLP
+// exporters parse OTEL_EXPORTER_OTLP_[<SIGNAL>_]ENDPOINT only as a URL, so
+// the common "localhost:4317" (no scheme) would parse "localhost" as the
+// scheme and fail every export with an empty host. A scheme-less value is
+// therefore passed through explicitly, like Config.Endpoint; a URL is left to
+// the exporter, which also derives the per-signal path from it.
+func explicitEndpoint(cfg Config, getenv func(string) string, kind signalKind) string {
+	if cfg.Endpoint != "" {
+		return cfg.Endpoint
+	}
+	v := firstNonEmpty(getenv("OTEL_EXPORTER_OTLP_"+string(kind)+"_ENDPOINT"), getenv("OTEL_EXPORTER_OTLP_ENDPOINT"))
+	if strings.Contains(v, "://") {
+		return ""
+	}
+	return v
+}
diff --git a/pkg/telemetry/otelsetup/setup.go b/pkg/telemetry/otelsetup/setup.go
index fc8499b..60ed70d 100644
--- a/pkg/telemetry/otelsetup/setup.go
+++ b/pkg/telemetry/otelsetup/setup.go
@@ -142,7 +142,7 @@ func Setup(ctx context.Context, cfg Config) (*Providers, func(context.Context) e
 func buildProviders(ctx context.Context, cfg Config, tracesPlan, metricsPlan signalPlan, res *resource.Resource) (*sdktrace.TracerProvider, *sdkmetric.MeterProvider, error) {
 	var tp *sdktrace.TracerProvider
 	if tracesPlan.enabled {
-		exp, err := newTraceExporter(ctx, cfg, tracesPlan.protocol)
+		exp, err := newTraceExporter(ctx, cfg, tracesPlan)
 		if err != nil {
 			return nil, nil, err
 		}
@@ -154,7 +154,7 @@ func buildProviders(ctx context.Context, cfg Config, tracesPlan, metricsPlan sig
 	}
 	var mp *sdkmetric.MeterProvider
 	if metricsPlan.enabled {
-		exp, err := newMetricExporter(ctx, cfg, metricsPlan.protocol)
+		exp, err := newMetricExporter(ctx, cfg, metricsPlan)
 		if err != nil {
 			if tp != nil {
 				_ = tp.Shutdown(ctx)
@@ -204,15 +204,16 @@ func buildResource(ctx context.Context, cfg Config) (*resource.Resource, error)
 	return res, nil
 }
 
-func newTraceExporter(ctx context.Context, cfg Config, protocol string) (sdktrace.SpanExporter, error) {
+func newTraceExporter(ctx context.Context, cfg Config, plan signalPlan) (sdktrace.SpanExporter, error) {
+	protocol := plan.protocol
 	var (
 		exp sdktrace.SpanExporter
 		err error
 	)
 	if protocol == ProtocolHTTP {
 		var opts []otlptracehttp.Option
-		if cfg.Endpoint != "" {
-			opts = append(opts, otlptracehttp.WithEndpoint(cfg.Endpoint))
+		if plan.endpoint != "" {
+			opts = append(opts, otlptracehttp.WithEndpoint(plan.endpoint))
 		}
 		if cfg.Insecure {
 			opts = append(opts, otlptracehttp.WithInsecure())
@@ -220,8 +221,8 @@ func newTraceExporter(ctx context.Context, cfg Config, protocol string) (sdktrac
 		exp, err = otlptracehttp.New(ctx, opts...)
 	} else {
 		var opts []otlptracegrpc.Option
-		if cfg.Endpoint != "" {
-			opts = append(opts, otlptracegrpc.WithEndpoint(cfg.Endpoint))
+		if plan.endpoint != "" {
+			opts = append(opts, otlptracegrpc.WithEndpoint(plan.endpoint))
 		}
 		if cfg.Insecure {
 			opts = append(opts, otlptracegrpc.WithInsecure())
@@ -234,15 +235,16 @@ func newTraceExporter(ctx context.Context, cfg Config, protocol string) (sdktrac
 	return exp, nil
 }
 
-func newMetricExporter(ctx context.Context, cfg Config, protocol string) (sdkmetric.Exporter, error) {
+func newMetricExporter(ctx context.Context, cfg Config, plan signalPlan) (sdkmetric.Exporter, error) {
+	protocol := plan.protocol
 	var (
 		exp sdkmetric.Exporter
 		err error
 	)
 	if protocol == ProtocolHTTP {
 		var opts []otlpmetrichttp.Option
-		if cfg.Endpoint != "" {
-			opts = append(opts, otlpmetrichttp.WithEndpoint(cfg.Endpoint))
+		if plan.endpoint != "" {
+			opts = append(opts, otlpmetrichttp.WithEndpoint(plan.endpoint))
 		}
 		if cfg.Insecure {
 			opts = append(opts, otlpmetrichttp.WithInsecure())
@@ -250,8 +252,8 @@ func newMetricExporter(ctx context.Context, cfg Config, protocol string) (sdkmet
 		exp, err = otlpmetrichttp.New(ctx, opts...)
 	} else {
 		var opts []otlpmetricgrpc.Option
-		if cfg.Endpoint != "" {
-			opts = append(opts, otlpmetricgrpc.WithEndpoint(cfg.Endpoint))
+		if plan.endpoint != "" {
+			opts = append(opts, otlpmetricgrpc.WithEndpoint(plan.endpoint))
 		}
 		if cfg.Insecure {
 			opts = append(opts, otlpmetricgrpc.WithInsecure())
diff --git a/pkg/telemetry/otelsetup/setup_test.go b/pkg/telemetry/otelsetup/setup_test.go
index bb89364..aa7bd6c 100644
--- a/pkg/telemetry/otelsetup/setup_test.go
+++ b/pkg/telemetry/otelsetup/setup_test.go
@@ -23,8 +23,13 @@ func TestResolveSignal(t *testing.T) {
 	}{
 		{name: "no endpoint stays off", want: signalPlan{}},
 		{
-			name: "generic endpoint defaults to grpc",
+			name: "scheme-less env endpoint is passed explicitly",
 			env:  map[string]string{"OTEL_EXPORTER_OTLP_ENDPOINT": "localhost:4317"},
+			want: signalPlan{enabled: true, protocol: ProtocolGRPC, endpoint: "localhost:4317"},
+		},
+		{
+			name: "URL env endpoint is left to the exporter",
+			env:  map[string]string{"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317"},
 			want: signalPlan{enabled: true, protocol: ProtocolGRPC},
 		},
 		{
@@ -40,7 +45,7 @@ func TestResolveSignal(t *testing.T) {
 			name: "config overrides env protocol",
 			cfg:  Config{Endpoint: "localhost:4318", Protocol: ProtocolHTTP},
 			env:  map[string]string{"OTEL_EXPORTER_OTLP_PROTOCOL": "grpc"},
-			want: signalPlan{enabled: true, protocol: ProtocolHTTP},
+			want: signalPlan{enabled: true, protocol: ProtocolHTTP, endpoint: "localhost:4318"},
 		},
 		{
 			name: "sdk disabled wins over endpoint",
diff --git a/pkg/telemetry/oteltools/middleware.go b/pkg/telemetry/oteltools/middleware.go
index e2e4e88..b7a2479 100644
--- a/pkg/telemetry/oteltools/middleware.go
+++ b/pkg/telemetry/oteltools/middleware.go
@@ -95,6 +95,9 @@ func Instrument(opts ...Option) tools.Middleware {
 	}
 
 	return func(next tools.Tool) tools.Tool {
+		if _, done := next.(*instrumentedTool); done {
+			return next // already instrumented: wrapping again would double every span
+		}
 		return &instrumentedTool{
 			Tool:     next,
 			name:     next.Descriptor().Name,
diff --git a/pkg/tools/registry_use_test.go b/pkg/tools/registry_use_test.go
new file mode 100644
index 0000000..88543b6
--- /dev/null
+++ b/pkg/tools/registry_use_test.go
@@ -0,0 +1,56 @@
+package tools
+
+import (
+	"context"
+	"testing"
+)
+
+type countTool struct {
+	Tool
+	calls *int
+}
+
+func (c countTool) Execute(ctx context.Context, args string) (Result, error) {
+	*c.calls++
+	return c.Tool.Execute(ctx, args)
+}
+
+type plainTool struct{ name string }
+
+func (p plainTool) Descriptor() ToolDescriptor { return ToolDescriptor{Name: p.name} }
+func (p plainTool) Execute(context.Context, string) (Result, error) {
+	return Text("ok"), nil
+}
+
+func TestRegistryUse_WrapsEveryRegisteredTool(t *testing.T) {
+	r := NewRegistry()
+	r.Register(plainTool{name: "a"})
+	r.Register(plainTool{name: "b"})
+	calls := 0
+	r.Use(func(next Tool) Tool { return countTool{Tool: next, calls: &calls} })
+	r.Register(plainTool{name: "late"})
+
+	for _, name := range []string{"a", "b", "late"} {
+		tool, ok := r.Get(name)
+		if !ok {
+			t.Fatalf("%s missing after Use — middleware must preserve names", name)
+		}
+		_, _ = tool.Execute(context.Background(), "{}")
+	}
+	if calls != 2 {
+		t.Fatalf("middleware ran %d times, want 2 (tools registered after Use stay unwrapped)", calls)
+	}
+}
+
+func TestRegistryUse_DebugModeWrapsRawTools(t *testing.T) {
+	r := NewRegistry()
+	r.EnableDebug(nil)
+	r.Register(plainTool{name: "a"})
+	calls := 0
+	r.Use(func(next Tool) Tool { return countTool{Tool: next, calls: &calls} })
+	tool, _ := r.Get("a")
+	_, _ = tool.Execute(context.Background(), "{}")
+	if calls != 1 {
+		t.Fatalf("middleware ran %d times in debug mode, want 1", calls)
+	}
+}
diff --git a/pkg/tools/tool.go b/pkg/tools/tool.go
index be64289..683d12f 100644
--- a/pkg/tools/tool.go
+++ b/pkg/tools/tool.go
@@ -232,6 +232,25 @@ func (r *Registry) Register(t Tool) {
 	}
 }
 
+// Use wraps every tool currently registered with mws, applied in order like
+// Chain — the way to instrument a registry that is already populated (e.g.
+// one a YAML builder produced). It wraps the registered tools themselves, not
+// their debug-logging views, and tools registered afterwards are not wrapped.
+// Middleware must preserve Descriptor().Name. Call it before the loop runs.
+func (r *Registry) Use(mws ...Middleware) {
+	if len(mws) == 0 {
+		return
+	}
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for name, t := range r.tools {
+		r.tools[name] = Chain(t, mws...)
+	}
+	if r.debug {
+		r.rebuildWrappedLocked()
+	}
+}
+
 // Get retrieves a tool by name. Returns false if not found.
 // When debug mode is enabled the tool is transparently wrapped with WithLogging.
 func (r *Registry) Get(name string) (Tool, bool) {

From 7ec184b6bba6592b2a5693288118821dd17a958e Mon Sep 17 00:00:00 2001
From: Hung Nguyen <hungit.khtn06@gmail.com>
Date: Tue, 3 Nov 2026 18:20:29 +0700
Subject: [PATCH 2/5] feat(auditlog): FromEnv, one-call Instrument, nil-safe
 Client

- FromEnv reads GOPHERAGENT_AUDIT_*; unset endpoint returns a nil client whose
  methods are no-ops, so the same code runs with auditing on or off.
- audit.Instrument(loop) wires tools, HITL, permissions and hook rejections.
- Config.DefaultTenantID (env default "default") so single-tenant apps need
  no WithActor; without it every record failed validation.
---
 pkg/auditlog/agent.go      |   3 +
 pkg/auditlog/client.go     |  17 ++++-
 pkg/auditlog/config.go     |   5 ++
 pkg/auditlog/setup.go      | 139 +++++++++++++++++++++++++++++++++++++
 pkg/auditlog/setup_test.go | 137 ++++++++++++++++++++++++++++++++++++
 5 files changed, 298 insertions(+), 3 deletions(-)
 create mode 100644 pkg/auditlog/setup.go
 create mode 100644 pkg/auditlog/setup_test.go

diff --git a/pkg/auditlog/agent.go b/pkg/auditlog/agent.go
index f5d3e21..9469e02 100644
--- a/pkg/auditlog/agent.go
+++ b/pkg/auditlog/agent.go
@@ -135,6 +135,9 @@ func ToolMiddleware(e Emitter, opts ...Option) tools.Middleware {
 	o := newOptions(opts)
 	fp, _ := e.(Fingerprinter)
 	return func(next tools.Tool) tools.Tool {
+		if _, done := next.(*auditedTool); done {
+			return next // already audited: wrapping again would double every record
+		}
 		desc := next.Descriptor()
 		level := LevelMetadata
 		if o.policy != nil {
diff --git a/pkg/auditlog/client.go b/pkg/auditlog/client.go
index 89123b0..d61d207 100644
--- a/pkg/auditlog/client.go
+++ b/pkg/auditlog/client.go
@@ -65,7 +65,9 @@ type exporter interface {
 }
 
 // Client ships audit events to an OTLP collector. It is safe for concurrent
-// use.
+// use. A nil *Client is a valid, disabled client: every method is a no-op, so
+// code can audit unconditionally and leave enabling it to configuration (see
+// FromEnv).
 type Client struct {
 	cfg     Config
 	res     *resourcepb.Resource
@@ -118,6 +120,9 @@ func New(ctx context.Context, cfg Config) (*Client, error) {
 // Send validates every event and delivers them per the client's Mode. If any
 // event is invalid, none is sent.
 func (c *Client) Send(ctx context.Context, events ...Event) error {
+	if c == nil {
+		return nil
+	}
 	c.mu.RLock()
 	defer c.mu.RUnlock() // held only across the non-blocking enqueue, never I/O
 	if c.closed {
@@ -134,6 +139,9 @@ func (c *Client) Send(ctx context.Context, events ...Event) error {
 
 // SendSync delivers synchronously regardless of Mode, like ModeBlocking.
 func (c *Client) SendSync(ctx context.Context, events ...Event) error {
+	if c == nil {
+		return nil
+	}
 	c.mu.RLock()
 	closed := c.closed
 	c.mu.RUnlock()
@@ -148,7 +156,7 @@ func (c *Client) SendSync(ctx context.Context, events ...Event) error {
 
 // Fingerprint returns Hash(HMACKey, value), or "" without a key.
 func (c *Client) Fingerprint(value string) string {
-	if c.cfg.HMACKey == nil {
+	if c == nil || c.cfg.HMACKey == nil {
 		return ""
 	}
 	return Hash(c.cfg.HMACKey, value)
@@ -157,7 +165,7 @@ func (c *Client) Fingerprint(value string) string {
 // Flush blocks until every event queued before the call is exported (or its
 // failure reported to OnError). A no-op in ModeBlocking.
 func (c *Client) Flush(ctx context.Context) error {
-	if c.batch == nil {
+	if c == nil || c.batch == nil {
 		return nil
 	}
 	return c.batch.flush(ctx)
@@ -166,6 +174,9 @@ func (c *Client) Flush(ctx context.Context) error {
 // Close drains the batch buffer (ModeBatch) and releases the connection.
 // Send fails with ErrClosed afterwards.
 func (c *Client) Close(ctx context.Context) error {
+	if c == nil {
+		return nil
+	}
 	c.mu.Lock()
 	if c.closed {
 		c.mu.Unlock()
diff --git a/pkg/auditlog/config.go b/pkg/auditlog/config.go
index dfd9c2b..b3556bb 100644
--- a/pkg/auditlog/config.go
+++ b/pkg/auditlog/config.go
@@ -46,6 +46,11 @@ type Config struct {
 	// MaxAttempts bounds retries of a transient export failure; default 3.
 	MaxAttempts int
 
+	// DefaultTenantID attributes records made by Instrument when the ctx
+	// carries no Actor tenant — what a single-tenant app sets instead of
+	// calling WithActor per request.
+	DefaultTenantID string
+
 	// HMACKey (at least 16 bytes) enables keyed argument fingerprints
 	// (ToolInvocation.ArgsHMAC) and a signature on every record, which Verify
 	// checks. Keep it out of the audit store: whoever holds it can forge
diff --git a/pkg/auditlog/setup.go b/pkg/auditlog/setup.go
new file mode 100644
index 0000000..431546e
--- /dev/null
+++ b/pkg/auditlog/setup.go
@@ -0,0 +1,139 @@
+package auditlog
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+	"os"
+	"strconv"
+	"strings"
+
+	"github.com/hung12ct/gopheragent/pkg/agent"
+)
+
+// Environment variables read by FromEnv. Only the endpoint is required; with
+// it unset, auditing is off.
+const (
+	EnvEndpoint    = "GOPHERAGENT_AUDIT_ENDPOINT"     // host:port — set it to turn auditing on
+	EnvProtocol    = "GOPHERAGENT_AUDIT_PROTOCOL"     // grpc (default) | http/protobuf
+	EnvInsecure    = "GOPHERAGENT_AUDIT_INSECURE"     // true: plaintext, local collectors only
+	EnvServiceName = "GOPHERAGENT_AUDIT_SERVICE_NAME" // default: OTEL_SERVICE_NAME, then "gopheragent"
+	EnvTenantID    = "GOPHERAGENT_AUDIT_TENANT_ID"    // default tenant when ctx has no Actor; default "default"
+	EnvHMACKey     = "GOPHERAGENT_AUDIT_HMAC_KEY"     // ≥16 bytes: keyed fingerprints + signed records
+	EnvHeaders     = "GOPHERAGENT_AUDIT_HEADERS"      // k=v,k2=v2 — e.g. authorization=Bearer%20token
+	EnvMode        = "GOPHERAGENT_AUDIT_MODE"         // blocking (default) | batch
+	EnvCAFile      = "GOPHERAGENT_AUDIT_CA_FILE"
+	EnvCertFile    = "GOPHERAGENT_AUDIT_CERT_FILE"
+	EnvKeyFile     = "GOPHERAGENT_AUDIT_KEY_FILE"
+)
+
+// FromEnv builds a Client from GOPHERAGENT_AUDIT_* environment variables.
+// With GOPHERAGENT_AUDIT_ENDPOINT unset it returns a nil *Client and no
+// error — a disabled client whose methods do nothing — so the same code runs
+// with auditing on or off:
+//
+//	audit, err := auditlog.FromEnv(ctx)
+//	if err != nil { ... }          // set but invalid configuration
+//	defer audit.Close(ctx)
+//	audit.Instrument(loop)
+func FromEnv(ctx context.Context) (*Client, error) {
+	cfg, ok, err := configFromEnv(os.Getenv)
+	if err != nil || !ok {
+		return nil, err
+	}
+	return New(ctx, cfg)
+}
+
+func configFromEnv(getenv func(string) string) (Config, bool, error) {
+	cfg := Config{Endpoint: strings.TrimSpace(getenv(EnvEndpoint))}
+	if cfg.Endpoint == "" {
+		return cfg, false, nil
+	}
+	cfg.Protocol = strings.TrimSpace(getenv(EnvProtocol))
+	cfg.ServiceName = firstSet(getenv(EnvServiceName), getenv("OTEL_SERVICE_NAME"), "gopheragent")
+	cfg.DefaultTenantID = firstSet(getenv(EnvTenantID), "default")
+	cfg.CAFile, cfg.CertFile, cfg.KeyFile = getenv(EnvCAFile), getenv(EnvCertFile), getenv(EnvKeyFile)
+	if k := getenv(EnvHMACKey); k != "" {
+		cfg.HMACKey = []byte(k)
+	}
+	if v := getenv(EnvInsecure); v != "" {
+		b, err := strconv.ParseBool(v)
+		if err != nil {
+			return cfg, false, fmt.Errorf("auditlog: %s=%q: %w", EnvInsecure, v, err)
+		}
+		cfg.Insecure = b
+	}
+	switch m := strings.ToLower(strings.TrimSpace(getenv(EnvMode))); m {
+	case "", "blocking":
+	case "batch":
+		cfg.Mode = ModeBatch
+	default:
+		return cfg, false, fmt.Errorf("auditlog: %s=%q: want blocking or batch", EnvMode, m)
+	}
+	headers, err := parseHeaders(getenv(EnvHeaders))
+	if err != nil {
+		return cfg, false, err
+	}
+	cfg.Headers = headers
+	return cfg, true, nil
+}
+
+// parseHeaders reads the OTEL_EXPORTER_OTLP_HEADERS format: comma-separated
+// key=value pairs, values percent-decoded.
+func parseHeaders(s string) (map[string]string, error) {
+	if strings.TrimSpace(s) == "" {
+		return nil, nil
+	}
+	out := map[string]string{}
+	for _, pair := range strings.Split(s, ",") {
+		k, v, ok := strings.Cut(pair, "=")
+		k = strings.TrimSpace(k)
+		if !ok || k == "" {
+			return nil, fmt.Errorf("auditlog: %s: %q is not key=value", EnvHeaders, pair)
+		}
+		dv, err := url.PathUnescape(strings.TrimSpace(v))
+		if err != nil {
+			return nil, fmt.Errorf("auditlog: %s: header %q: %w", EnvHeaders, k, err)
+		}
+		out[k] = dv
+	}
+	return out, nil
+}
+
+func firstSet(vals ...string) string {
+	for _, v := range vals {
+		if v = strings.TrimSpace(v); v != "" {
+			return v
+		}
+	}
+	return ""
+}
+
+// Instrument audits an already-built loop in one call: every tool in
+// loop.Tools (ToolMiddleware), the HITL callback (AuditConfirm), the
+// permission policy (AuditPermissions), and hook rejections (EventHandler).
+// opts are passed to each, e.g. WithFailClosed or WithPolicy. Records fall
+// back to Config.DefaultTenantID when the ctx carries no Actor.
+//
+// Call it last — after ConfirmHITL, Permissions, and the tools are set; ones
+// set afterwards are not audited. Tools are never double-wrapped, but the
+// callback, policy, and event handler are, so call it once per loop. A nil
+// client changes nothing. Returns loop for chaining.
+func (c *Client) Instrument(loop *agent.AgentLoop, opts ...Option) *agent.AgentLoop {
+	if c == nil || loop == nil {
+		return loop
+	}
+	if c.cfg.DefaultTenantID != "" {
+		opts = append([]Option{WithDefaultTenant(c.cfg.DefaultTenantID)}, opts...) // caller's options win
+	}
+	if loop.Tools != nil {
+		loop.Tools.Use(ToolMiddleware(c, opts...))
+	}
+	if loop.ConfirmHITL != nil {
+		loop.ConfirmHITL = AuditConfirm(loop.ConfirmHITL, c, opts...)
+	}
+	if loop.Permissions != nil {
+		loop.Permissions = AuditPermissions(loop.Permissions, c, opts...)
+	}
+	return loop.OnEvent(EventHandler(c, opts...))
+}
diff --git a/pkg/auditlog/setup_test.go b/pkg/auditlog/setup_test.go
new file mode 100644
index 0000000..6b21d32
--- /dev/null
+++ b/pkg/auditlog/setup_test.go
@@ -0,0 +1,137 @@
+package auditlog
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/hung12ct/gopheragent/pkg/agent"
+	"github.com/hung12ct/gopheragent/pkg/history"
+	"github.com/hung12ct/gopheragent/pkg/tools"
+)
+
+func TestConfigFromEnv(t *testing.T) {
+	env := func(m map[string]string) func(string) string { return func(k string) string { return m[k] } }
+
+	if _, ok, err := configFromEnv(env(nil)); ok || err != nil {
+		t.Fatalf("no endpoint must mean disabled, no error: ok=%v err=%v", ok, err)
+	}
+	cfg, ok, err := configFromEnv(env(map[string]string{
+		EnvEndpoint: "collector:4317", EnvInsecure: "true", EnvMode: "batch", EnvHMACKey: "0123456789abcdef",
+		EnvHeaders: "authorization=Bearer%20tok, x-team=core", "OTEL_SERVICE_NAME": "billing",
+	}))
+	if err != nil || !ok {
+		t.Fatalf("ok=%v err=%v", ok, err)
+	}
+	if !cfg.Insecure || cfg.Mode != ModeBatch || string(cfg.HMACKey) != "0123456789abcdef" || cfg.ServiceName != "billing" {
+		t.Fatalf("cfg = %+v", cfg)
+	}
+	if cfg.Headers["authorization"] != "Bearer tok" || cfg.Headers["x-team"] != "core" {
+		t.Fatalf("headers = %v", cfg.Headers)
+	}
+	for _, bad := range []map[string]string{
+		{EnvEndpoint: "c:1", EnvInsecure: "maybe"},
+		{EnvEndpoint: "c:1", EnvMode: "async"},
+		{EnvEndpoint: "c:1", EnvHeaders: "novalue"},
+	} {
+		if _, _, err := configFromEnv(env(bad)); err == nil {
+			t.Fatalf("invalid env %v accepted", bad)
+		}
+	}
+	if cfg, _, _ := configFromEnv(env(map[string]string{EnvEndpoint: "c:1"})); cfg.ServiceName != "gopheragent" || cfg.DefaultTenantID != "default" {
+		t.Fatalf("defaults: service=%q tenant=%q", cfg.ServiceName, cfg.DefaultTenantID)
+	}
+}
+
+func TestFromEnv_UnsetIsANilClientThatDoesNothing(t *testing.T) {
+	t.Setenv(EnvEndpoint, "")
+	c, err := FromEnv(context.Background())
+	if c != nil || err != nil {
+		t.Fatalf("FromEnv without endpoint = %v, %v; want nil, nil", c, err)
+	}
+	ctx := context.Background()
+	if c.Send(ctx, sampleEvent) != nil || c.SendSync(ctx, sampleEvent) != nil || c.Flush(ctx) != nil || c.Close(ctx) != nil || c.Fingerprint("x") != "" {
+		t.Fatal("every method of a nil client must be a no-op")
+	}
+	loop := agent.New(history.NewInMemSessionManager("sys"), tools.NewRegistry(), &scriptLLM{})
+	if c.Instrument(loop) != loop || len(loop.EventHandlers) != 0 {
+		t.Fatal("a nil client's Instrument must not touch the loop")
+	}
+}
+
+// TestInstrument_OneCallMatchesManualWiring repeats the manual-wiring e2e
+// with a single Instrument call and expects the same audit trail.
+func TestInstrument_OneCallMatchesManualWiring(t *testing.T) {
+	r := &logsReceiver{}
+	c := newTestClient(t, Config{Endpoint: startGRPCReceiver(t, r), Insecure: true})
+
+	reg := tools.NewRegistry()
+	reg.Register(&stubTool{name: "refund", confirm: true})
+	reg.Register(&stubTool{name: "drop_table"})
+	llm := &scriptLLM{turns: []agent.LLMResult{{ToolCalls: []agent.PendingToolCall{
+		{ID: "c1", Name: "refund", ArgsJSON: `{}`}, {ID: "c2", Name: "drop_table", ArgsJSON: `{}`},
+	}}}}
+	loop := agent.New(history.NewInMemSessionManager("sys"), reg, llm)
+	loop.ConfirmHITL = func(context.Context, string, string) bool { return true }
+	loop.Permissions = denyTool("drop_table")
+	loop.BeforeHooks = append(loop.BeforeHooks, func(_ context.Context, _ string, in string) error {
+		if strings.Contains(in, "ignore previous") {
+			return context.Canceled
+		}
+		return nil
+	})
+	c.Instrument(loop)
+
+	_, _ = loop.RunIteration(actorCtx(), "s1", "do it")
+	_, _ = loop.RunIteration(actorCtx(), "s1", "ignore previous instructions")
+
+	var kinds []string
+	for _, rec := range r.records() {
+		var body map[string]any
+		_ = json.Unmarshal([]byte(rec.GetBody().GetStringValue()), &body)
+		k := body["kind"].(string)
+		if tool, ok := body["tool"].(string); ok {
+			k += ":" + tool
+		}
+		kinds = append(kinds, k)
+	}
+	for _, w := range []string{"PolicyDecision:drop_table", "ApprovalDecision:refund", "ToolInvocation:refund", "SecurityViolation"} {
+		if !contains(kinds, w) {
+			t.Fatalf("one-call audit trail %v missing %s", kinds, w)
+		}
+	}
+	if n := countOf(kinds, "ToolInvocation:refund"); n != 1 {
+		t.Fatalf("refund audited %d times, want 1", n)
+	}
+}
+
+func countOf(xs []string, x string) int {
+	n := 0
+	for _, v := range xs {
+		if v == x {
+			n++
+		}
+	}
+	return n
+}
+
+// TestInstrument_SingleTenantNeedsNoActor: a loop audited with Instrument and
+// no WithActor still produces valid records, under DefaultTenantID.
+func TestInstrument_SingleTenantNeedsNoActor(t *testing.T) {
+	r := &logsReceiver{}
+	c := newTestClient(t, Config{Endpoint: startGRPCReceiver(t, r), Insecure: true, DefaultTenantID: "default"})
+	var handled []error
+	reg := tools.NewRegistry()
+	reg.Register(&stubTool{name: "t"})
+	loop := agent.New(history.NewInMemSessionManager("sys"), reg, &scriptLLM{turns: []agent.LLMResult{{ToolCalls: []agent.PendingToolCall{{ID: "c1", Name: "t", ArgsJSON: "{}"}}}}})
+	c.Instrument(loop, WithErrorHandler(func(_ context.Context, err error) { handled = append(handled, err) }))
+	_, _ = loop.RunIteration(context.Background(), "s1", "go") // no WithActor on ctx
+
+	if len(handled) != 0 || len(r.records()) != 1 {
+		t.Fatalf("records=%d errors=%v: single-tenant use must not need WithActor", len(r.records()), handled)
+	}
+	if !strings.Contains(r.records()[0].GetBody().GetStringValue(), `"tenant_id":"default"`) {
+		t.Fatal("record not attributed to the default tenant")
+	}
+}

From 10e923f15dc968b4c287bfe2f116820e6bcb91e9 Mon Sep 17 00:00:00 2001
From: Hung Nguyen <hungit.khtn06@gmail.com>
Date: Tue, 3 Nov 2026 18:20:29 +0700
Subject: [PATCH 3/5] refactor(demo): wire telemetry and audit with one
 Instrument call each

---
 examples/demo/main.go | 70 ++++++++++++++++++++-----------------------
 1 file changed, 32 insertions(+), 38 deletions(-)

diff --git a/examples/demo/main.go b/examples/demo/main.go
index dfc8030..6968090 100644
--- a/examples/demo/main.go
+++ b/examples/demo/main.go
@@ -17,6 +17,7 @@ import (
 	"go.opentelemetry.io/otel/propagation"
 
 	"github.com/hung12ct/gopheragent/pkg/agent"
+	"github.com/hung12ct/gopheragent/pkg/auditlog"
 	"github.com/hung12ct/gopheragent/pkg/builder"
 	"github.com/hung12ct/gopheragent/pkg/history"
 	"github.com/hung12ct/gopheragent/pkg/llm/anthropic"
@@ -24,7 +25,6 @@ import (
 	"github.com/hung12ct/gopheragent/pkg/llm/openai"
 	"github.com/hung12ct/gopheragent/pkg/telemetry/otelllm"
 	"github.com/hung12ct/gopheragent/pkg/telemetry/otelsetup"
-	"github.com/hung12ct/gopheragent/pkg/telemetry/oteltools"
 	"github.com/hung12ct/gopheragent/pkg/tools/builtin"
 )
 
@@ -32,6 +32,10 @@ import (
 // all demo instrumentation.
 var telProviders *otelsetup.Providers
 
+// auditClient ships audit events when GOPHERAGENT_AUDIT_ENDPOINT is set; nil
+// (a disabled client) otherwise.
+var auditClient *auditlog.Client
+
 var myAgentApp *agent.AgentLoop
 
 // agentInfo exposes the loaded YAML config to the frontend so the UI can
@@ -68,48 +72,42 @@ func loadEnvFiles() {
 	}
 }
 
-// instrumentLLM wraps p with the OTel decorator when telemetry is enabled,
-// tagging spans/metrics with the vendor and model. A no-op otherwise.
-func instrumentLLM(p agent.LLMProvider, system, model string) agent.LLMProvider {
-	if telProviders == nil {
-		return p
-	}
-	return otelllm.NewProvider(p,
-		otelllm.WithSystem(system), otelllm.WithModel(model),
-		otelllm.WithTracer(telProviders.Tracer), otelllm.WithMeter(telProviders.Meter))
-}
-
-func buildProvider() agent.LLMProvider {
+// buildProvider returns the configured LLM plus its vendor and model, which
+// label the telemetry.
+func buildProvider() (p agent.LLMProvider, system, model string) {
 	provider := strings.ToLower(strings.TrimSpace(os.Getenv("LLM_PROVIDER")))
 	log.Printf("LLM_PROVIDER=%q", provider)
 	switch provider {
 	case "openai":
 		model := strings.TrimSpace(os.Getenv("OPENAI_MODEL"))
-		p, err := openai.New("", model)
+		op, err := openai.New("", model)
+		p = op
 		if err == nil {
 			log.Printf("Using OpenAI provider")
-			return instrumentLLM(p, "openai", model)
+			return p, "openai", model
 		}
 		log.Printf("Warning: OpenAI provider init failed: %v", err)
 	case "anthropic", "claude":
 		model := strings.TrimSpace(os.Getenv("ANTHROPIC_MODEL"))
-		p, err := anthropic.New("", model)
+		ap, err := anthropic.New("", model)
+		p = ap
 		if err == nil {
 			log.Printf("Using Anthropic provider")
-			return instrumentLLM(p, "anthropic", model)
+			return p, "anthropic", model
 		}
 		log.Printf("Warning: Anthropic provider init failed: %v", err)
 	case "gemini":
 		model := strings.TrimSpace(os.Getenv("GEMINI_MODEL"))
-		p, err := gemini.New("", model)
+		gp, err := gemini.New("", model)
+		p = gp
 		if err == nil {
 			log.Printf("Using Gemini provider")
-			return instrumentLLM(p, "gemini", model)
+			return p, "gemini", model
 		}
 		log.Printf("Warning: Gemini provider init failed: %v", err)
 	}
 	log.Printf("Using Mock provider (set LLM_PROVIDER=openai|anthropic|gemini to use real model)")
-	return agent.NewMockProvider()
+	return agent.NewMockProvider(), "mock", ""
 }
 
 func SecurityHook(ctx context.Context, sessionKey string, userInput string) error {
@@ -370,14 +368,6 @@ func getStream(sessionKey string) chan<- agent.StreamEvent {
 func initApp() {
 	catalog := builder.NewGlobalCatalog()
 
-	// Instrument every catalog tool with per-Execute spans + latency metrics.
-	// Must run before the loop is built so tools are wrapped at registration.
-	if telProviders != nil {
-		catalog.Use(oteltools.Instrument(
-			oteltools.WithTracer(telProviders.Tracer),
-			oteltools.WithMeter(telProviders.Meter)))
-	}
-
 	// Web tools — Register* helpers use tools.RegisterFunc internally
 	// so the catalog gets a typed-args funcTool without the per-tool
 	// struct boilerplate.
@@ -434,7 +424,8 @@ func initApp() {
 		log.Printf("Background summarizer enabled (gpt-4o-mini)")
 	}
 
-	loop, _, _, err := builder.BuildFromYAMLWithSession(yamlPath, catalog, buildProvider(), SecurityHook, sm)
+	llm, llmSystem, llmModel := buildProvider()
+	loop, _, _, err := builder.BuildFromYAMLWithSession(yamlPath, catalog, llm, SecurityHook, sm)
 	if err != nil {
 		log.Fatalf("Failed to build demo agent from YAML (%s): %v", yamlPath, err)
 	}
@@ -444,11 +435,10 @@ func initApp() {
 	loop.ConfirmPlan = buildConfirmPlan()
 	planModeDefault = os.Getenv("PLAN_MODE") == "true"
 
-	// Open a run/iteration span per turn so LLM (via the decorated provider) and
-	// tool (via catalog middleware) spans nest into one trace per conversation.
-	if telProviders != nil {
-		loop.Configure(agent.WithTracer(telProviders.Tracer), agent.WithMeter(telProviders.Meter))
-	}
+	// One call each, after the loop is fully configured. Both are no-ops when
+	// their endpoint isn't set (telProviders / auditClient are nil).
+	telProviders.Instrument(loop, otelllm.WithSystem(llmSystem), otelllm.WithModel(llmModel))
+	auditClient.Instrument(loop)
 
 	myAgentApp = loop
 	log.Printf("Demo loaded: %s", yamlPath)
@@ -587,10 +577,8 @@ func ChatHandler(w http.ResponseWriter, r *http.Request) {
 // setupTelemetry wires OpenTelemetry OTLP export. otelsetup.Setup stays off
 // unless OTEL_EXPORTER_OTLP_ENDPOINT (or a per-signal endpoint) is set, and
 // honors OTEL_SDK_DISABLED / OTEL_*_EXPORTER=none / OTEL_EXPORTER_OTLP_PROTOCOL.
-// Returns a shutdown func to flush exporters, or nil when telemetry is disabled.
-// It sets telProviders; the rest of the wiring (provider decorator, catalog tool
-// middleware, loop.Configure) reads that global so a YAML-built agent still gets
-// fully nested invoke_agent → iteration → chat → execute_tool spans.
+// Returns a shutdown func to flush exporters, or nil when telemetry is
+// disabled. initApp instruments the loop with one telProviders.Instrument call.
 func setupTelemetry() func(context.Context) error {
 	tel, shutdown, err := otelsetup.Setup(context.Background(), otelsetup.Config{
 		ServiceName: "gopheragent-demo",
@@ -627,6 +615,12 @@ func main() {
 	if shutdown != nil {
 		defer func() { _ = shutdown(context.Background()) }()
 	}
+	// Auditing is on only when GOPHERAGENT_AUDIT_ENDPOINT is set.
+	var err error
+	if auditClient, err = auditlog.FromEnv(context.Background()); err != nil {
+		log.Fatalf("audit log config: %v", err)
+	}
+	defer func() { _ = auditClient.Close(context.Background()) }()
 	initApp()
 	http.Handle("/", http.FileServer(http.Dir("./frontend")))
 	http.HandleFunc("/api/chat", withTraceContext(ChatHandler))

From 9dc7549827f966c26d0b4881ce6892f125502b45 Mon Sep 17 00:00:00 2001
From: Hung Nguyen <hungit.khtn06@gmail.com>
Date: Tue, 3 Nov 2026 18:21:14 +0700
Subject: [PATCH 4/5] docs(auditlog): env + one-call setup

---
 docs/auditlog.md | 37 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/docs/auditlog.md b/docs/auditlog.md
index 09a12bb..55acbdf 100644
--- a/docs/auditlog.md
+++ b/docs/auditlog.md
@@ -16,7 +16,42 @@ acknowledged the record, or with the error that prevented it.** Nothing is
 buffered; a nil return means written. High-volume events can opt into
 `ModeBatch` — see [Delivery modes](#delivery-modes).
 
-## Set up
+## The short way: env + one call
+
+```go
+audit, err := auditlog.FromEnv(ctx) // GOPHERAGENT_AUDIT_ENDPOINT unset → nil client: auditing off
+if err != nil { /* set but invalid configuration */ }
+defer audit.Close(ctx)
+
+audit.Instrument(loop) // tools, HITL approvals, permission verdicts, hook rejections
+```
+
+```bash
+export GOPHERAGENT_AUDIT_ENDPOINT=collector:4317
+export GOPHERAGENT_AUDIT_INSECURE=true          # local collectors only
+export GOPHERAGENT_AUDIT_HMAC_KEY=...            # optional: signed records, keyed fingerprints
+```
+
+A nil `*Client` is a valid, disabled client — every method is a no-op — so
+the same code runs with auditing on or off. Call `Instrument` last, after
+`ConfirmHITL`, `Permissions`, and the tools are set, and once per loop.
+Records fall back to `GOPHERAGENT_AUDIT_TENANT_ID` (default `"default"`)
+when the request ctx carries no `Actor`; multi-tenant apps set the actor per
+request with `auditlog.WithActor`.
+
+| Variable | Meaning |
+|---|---|
+| `GOPHERAGENT_AUDIT_ENDPOINT` | `host:port` — set it to turn auditing on |
+| `GOPHERAGENT_AUDIT_PROTOCOL` | `grpc` (default) or `http/protobuf` |
+| `GOPHERAGENT_AUDIT_INSECURE` | `true` for plaintext |
+| `GOPHERAGENT_AUDIT_SERVICE_NAME` | default `OTEL_SERVICE_NAME`, then `gopheragent` |
+| `GOPHERAGENT_AUDIT_TENANT_ID` | tenant when ctx has no `Actor`; default `default` |
+| `GOPHERAGENT_AUDIT_HMAC_KEY` | ≥16 bytes: keyed fingerprints and signed records |
+| `GOPHERAGENT_AUDIT_HEADERS` | `k=v,k2=v2`, values percent-encoded |
+| `GOPHERAGENT_AUDIT_MODE` | `blocking` (default) or `batch` |
+| `GOPHERAGENT_AUDIT_CA_FILE` / `_CERT_FILE` / `_KEY_FILE` | TLS / mTLS |
+
+## Set up in code
 
 ```go
 c, err := auditlog.New(ctx, auditlog.Config{

From f4b91580a0c247eec65fd15bd127ba8351a7334b Mon Sep 17 00:00:00 2001
From: Hung Nguyen <hungit.khtn06@gmail.com>
Date: Tue, 3 Nov 2026 18:59:07 +0700
Subject: [PATCH 5/5] feat: guard the one-call setup against silent
 misconfiguration

- GOPHERAGENT_AUDIT_REQUIRED=true makes a missing endpoint an error instead
  of silently disabling auditing.
- FromEnv reports audit health on the global OTel meter, so failed/dropped
  records alert without extra wiring.
- Both Instrument calls warn once about tools, HITL or permissions attached
  after them (compared by name, no false alarm on extra middleware).
---
 docs/auditlog.md                      |  6 ++-
 docs/observability.md                 |  3 +-
 internal/latewire/latewire.go         | 55 ++++++++++++++++++++
 internal/latewire/latewire_test.go    | 73 +++++++++++++++++++++++++++
 pkg/auditlog/setup.go                 | 26 +++++++++-
 pkg/auditlog/setup_test.go            | 59 ++++++++++++++++++++++
 pkg/telemetry/otelsetup/instrument.go |  5 +-
 7 files changed, 222 insertions(+), 5 deletions(-)
 create mode 100644 internal/latewire/latewire.go
 create mode 100644 internal/latewire/latewire_test.go

diff --git a/docs/auditlog.md b/docs/auditlog.md
index 55acbdf..335fb14 100644
--- a/docs/auditlog.md
+++ b/docs/auditlog.md
@@ -34,7 +34,10 @@ export GOPHERAGENT_AUDIT_HMAC_KEY=...            # optional: signed records, key
 
 A nil `*Client` is a valid, disabled client — every method is a no-op — so
 the same code runs with auditing on or off. Call `Instrument` last, after
-`ConfirmHITL`, `Permissions`, and the tools are set, and once per loop.
+`ConfirmHITL`, `Permissions`, and the tools are set, and once per loop;
+anything attached later is named in a log warning on the loop's first event.
+The client's health metrics (`gopheragent.audit.records{result=failed|dropped}`)
+go to the global OTel meter, so with telemetry enabled they need no wiring.
 Records fall back to `GOPHERAGENT_AUDIT_TENANT_ID` (default `"default"`)
 when the request ctx carries no `Actor`; multi-tenant apps set the actor per
 request with `auditlog.WithActor`.
@@ -42,6 +45,7 @@ request with `auditlog.WithActor`.
 | Variable | Meaning |
 |---|---|
 | `GOPHERAGENT_AUDIT_ENDPOINT` | `host:port` — set it to turn auditing on |
+| `GOPHERAGENT_AUDIT_REQUIRED` | `true`: a missing (or misspelled) endpoint fails `FromEnv` instead of turning auditing off — set it wherever audit is mandatory |
 | `GOPHERAGENT_AUDIT_PROTOCOL` | `grpc` (default) or `http/protobuf` |
 | `GOPHERAGENT_AUDIT_INSECURE` | `true` for plaintext |
 | `GOPHERAGENT_AUDIT_SERVICE_NAME` | default `OTEL_SERVICE_NAME`, then `gopheragent` |
diff --git a/docs/observability.md b/docs/observability.md
index 27223da..97f06a5 100644
--- a/docs/observability.md
+++ b/docs/observability.md
@@ -72,7 +72,8 @@ tel.Instrument(loop, otelllm.WithSystem("anthropic"), otelllm.WithModel(model))
 `Instrument` wires the loop (run/iteration spans, run metrics), its LLM (chat
 spans, token metrics), and every registered tool (execute_tool spans) — for a
 loop from `agent.New` or the YAML builder alike. Call it after the tools are
-registered; calling it twice is harmless. With no endpoint configured it does
+registered (tools registered later are named in a log warning on the loop's
+first event); calling it twice is harmless. With no endpoint configured it does
 nothing, so call it unconditionally and enable telemetry purely with env:
 
 ```bash
diff --git a/internal/latewire/latewire.go b/internal/latewire/latewire.go
new file mode 100644
index 0000000..e285adf
--- /dev/null
+++ b/internal/latewire/latewire.go
@@ -0,0 +1,55 @@
+// Package latewire catches the one way the one-call Instrument helpers fail
+// silently: something attached to the loop after Instrument ran.
+package latewire
+
+import (
+	"context"
+	"log"
+	"slices"
+	"sync"
+
+	"github.com/hung12ct/gopheragent/pkg/agent"
+	"github.com/hung12ct/gopheragent/pkg/tools"
+)
+
+// Watch snapshots what Instrument covered and, on the loop's first event —
+// once, so it costs nothing afterwards — logs a warning naming anything
+// attached later: tools, and with hooks, the HITL callback and permission
+// policy. Compared by name, so wrapping a tool in more middleware is not a
+// false alarm.
+func Watch(loop *agent.AgentLoop, component string, hooks bool) {
+	known := names(loop.Tools)
+	hadHITL, hadPerms := loop.ConfirmHITL != nil, loop.Permissions != nil
+	var once sync.Once
+	loop.OnEvent(func(context.Context, string, agent.StreamEvent) {
+		once.Do(func() {
+			var late []string
+			for _, n := range names(loop.Tools) {
+				if !slices.Contains(known, n) {
+					late = append(late, "tool "+n)
+				}
+			}
+			if hooks && !hadHITL && loop.ConfirmHITL != nil {
+				late = append(late, "ConfirmHITL")
+			}
+			if hooks && !hadPerms && loop.Permissions != nil {
+				late = append(late, "Permissions")
+			}
+			if len(late) > 0 {
+				log.Printf("[gopheragent] %s: %v attached after Instrument and not covered — call Instrument last", component, late)
+			}
+		})
+	})
+}
+
+func names(r *tools.Registry) []string {
+	if r == nil {
+		return nil
+	}
+	all := r.All()
+	out := make([]string, 0, len(all))
+	for _, t := range all {
+		out = append(out, t.Descriptor().Name)
+	}
+	return out
+}
diff --git a/internal/latewire/latewire_test.go b/internal/latewire/latewire_test.go
new file mode 100644
index 0000000..4b74897
--- /dev/null
+++ b/internal/latewire/latewire_test.go
@@ -0,0 +1,73 @@
+package latewire
+
+import (
+	"bytes"
+	"context"
+	"log"
+	"strings"
+	"testing"
+
+	"github.com/hung12ct/gopheragent/pkg/agent"
+	"github.com/hung12ct/gopheragent/pkg/history"
+	"github.com/hung12ct/gopheragent/pkg/tools"
+)
+
+type answerLLM struct{}
+
+func (answerLLM) GenerateStream(context.Context, []history.Message, *tools.Registry, chan<- agent.StreamEvent) (agent.LLMResult, error) {
+	return agent.LLMResult{Content: "ok"}, nil
+}
+
+type namedTool string
+
+func (n namedTool) Descriptor() tools.ToolDescriptor { return tools.ToolDescriptor{Name: string(n)} }
+func (namedTool) Execute(context.Context, string) (tools.Result, error) {
+	return tools.Text("ok"), nil
+}
+
+// captureLog runs fn and returns what it logged.
+func captureLog(t *testing.T, fn func()) string {
+	t.Helper()
+	var buf bytes.Buffer
+	prev, flags := log.Writer(), log.Flags()
+	log.SetOutput(&buf)
+	t.Cleanup(func() { log.SetOutput(prev); log.SetFlags(flags) })
+	fn()
+	return buf.String()
+}
+
+func newLoop(toolNames ...string) *agent.AgentLoop {
+	reg := tools.NewRegistry()
+	for _, n := range toolNames {
+		reg.Register(namedTool(n))
+	}
+	return agent.New(history.NewInMemSessionManager("sys"), reg, answerLLM{})
+}
+
+func TestWatch_WarnsOnceAboutLateAttachments(t *testing.T) {
+	loop := newLoop("early")
+	Watch(loop, "auditlog", true)
+	loop.Tools.Register(namedTool("late"))
+	loop.ConfirmHITL = func(context.Context, string, string) bool { return true }
+
+	out := captureLog(t, func() {
+		_, _ = loop.RunIteration(context.Background(), "s", "a")
+		_, _ = loop.RunIteration(context.Background(), "s", "b")
+	})
+	if !strings.Contains(out, "tool late") || !strings.Contains(out, "ConfirmHITL") || strings.Contains(out, "tool early") {
+		t.Fatalf("warning = %q, want it to name the late tool and ConfirmHITL only", out)
+	}
+	if strings.Count(out, "attached after Instrument") != 1 {
+		t.Fatalf("warned %d times, want once", strings.Count(out, "attached after Instrument"))
+	}
+}
+
+func TestWatch_SilentWhenInstrumentIsLast(t *testing.T) {
+	loop := newLoop("a", "b")
+	loop.ConfirmHITL = func(context.Context, string, string) bool { return true }
+	Watch(loop, "auditlog", true)
+	loop.Tools.Use(func(next tools.Tool) tools.Tool { return next }) // more wrapping is not "late"
+	if out := captureLog(t, func() { _, _ = loop.RunIteration(context.Background(), "s", "q") }); out != "" {
+		t.Fatalf("unexpected warning: %q", out)
+	}
+}
diff --git a/pkg/auditlog/setup.go b/pkg/auditlog/setup.go
index 431546e..3d299fb 100644
--- a/pkg/auditlog/setup.go
+++ b/pkg/auditlog/setup.go
@@ -8,6 +8,9 @@ import (
 	"strconv"
 	"strings"
 
+	"go.opentelemetry.io/otel"
+
+	"github.com/hung12ct/gopheragent/internal/latewire"
 	"github.com/hung12ct/gopheragent/pkg/agent"
 )
 
@@ -15,6 +18,7 @@ import (
 // it unset, auditing is off.
 const (
 	EnvEndpoint    = "GOPHERAGENT_AUDIT_ENDPOINT"     // host:port — set it to turn auditing on
+	EnvRequired    = "GOPHERAGENT_AUDIT_REQUIRED"     // true: a missing endpoint is an error, not "off"
 	EnvProtocol    = "GOPHERAGENT_AUDIT_PROTOCOL"     // grpc (default) | http/protobuf
 	EnvInsecure    = "GOPHERAGENT_AUDIT_INSECURE"     // true: plaintext, local collectors only
 	EnvServiceName = "GOPHERAGENT_AUDIT_SERVICE_NAME" // default: OTEL_SERVICE_NAME, then "gopheragent"
@@ -30,7 +34,13 @@ const (
 // FromEnv builds a Client from GOPHERAGENT_AUDIT_* environment variables.
 // With GOPHERAGENT_AUDIT_ENDPOINT unset it returns a nil *Client and no
 // error — a disabled client whose methods do nothing — so the same code runs
-// with auditing on or off:
+// with auditing on or off. Where auditing is mandatory, set
+// GOPHERAGENT_AUDIT_REQUIRED=true so a missing or misspelled endpoint fails
+// startup instead of silently disabling the trail.
+//
+// The client's self-health metrics go to the global OTel MeterProvider, so
+// with telemetry enabled (otelsetup.Setup, before or after) failed and dropped
+// records are visible without extra wiring:
 //
 //	audit, err := auditlog.FromEnv(ctx)
 //	if err != nil { ... }          // set but invalid configuration
@@ -41,12 +51,22 @@ func FromEnv(ctx context.Context) (*Client, error) {
 	if err != nil || !ok {
 		return nil, err
 	}
+	cfg.Meter = otel.GetMeterProvider().Meter(scopeName)
 	return New(ctx, cfg)
 }
 
 func configFromEnv(getenv func(string) string) (Config, bool, error) {
 	cfg := Config{Endpoint: strings.TrimSpace(getenv(EnvEndpoint))}
 	if cfg.Endpoint == "" {
+		if v := getenv(EnvRequired); v != "" {
+			required, err := strconv.ParseBool(v)
+			if err != nil {
+				return cfg, false, fmt.Errorf("auditlog: %s=%q: %w", EnvRequired, v, err)
+			}
+			if required {
+				return cfg, false, fmt.Errorf("auditlog: %s is set but %s is empty", EnvRequired, EnvEndpoint)
+			}
+		}
 		return cfg, false, nil
 	}
 	cfg.Protocol = strings.TrimSpace(getenv(EnvProtocol))
@@ -116,7 +136,8 @@ func firstSet(vals ...string) string {
 // back to Config.DefaultTenantID when the ctx carries no Actor.
 //
 // Call it last — after ConfirmHITL, Permissions, and the tools are set; ones
-// set afterwards are not audited. Tools are never double-wrapped, but the
+// set afterwards are not audited (a warning names them on the loop's first
+// event). Tools are never double-wrapped, but the
 // callback, policy, and event handler are, so call it once per loop. A nil
 // client changes nothing. Returns loop for chaining.
 func (c *Client) Instrument(loop *agent.AgentLoop, opts ...Option) *agent.AgentLoop {
@@ -126,6 +147,7 @@ func (c *Client) Instrument(loop *agent.AgentLoop, opts ...Option) *agent.AgentL
 	if c.cfg.DefaultTenantID != "" {
 		opts = append([]Option{WithDefaultTenant(c.cfg.DefaultTenantID)}, opts...) // caller's options win
 	}
+	latewire.Watch(loop, "auditlog", true)
 	if loop.Tools != nil {
 		loop.Tools.Use(ToolMiddleware(c, opts...))
 	}
diff --git a/pkg/auditlog/setup_test.go b/pkg/auditlog/setup_test.go
index 6b21d32..0801ce9 100644
--- a/pkg/auditlog/setup_test.go
+++ b/pkg/auditlog/setup_test.go
@@ -3,9 +3,14 @@ package auditlog
 import (
 	"context"
 	"encoding/json"
+	"log"
 	"strings"
 	"testing"
 
+	"go.opentelemetry.io/otel"
+	sdkmetric "go.opentelemetry.io/otel/sdk/metric"
+	"go.opentelemetry.io/otel/sdk/metric/metricdata"
+
 	"github.com/hung12ct/gopheragent/pkg/agent"
 	"github.com/hung12ct/gopheragent/pkg/history"
 	"github.com/hung12ct/gopheragent/pkg/tools"
@@ -34,11 +39,17 @@ func TestConfigFromEnv(t *testing.T) {
 		{EnvEndpoint: "c:1", EnvInsecure: "maybe"},
 		{EnvEndpoint: "c:1", EnvMode: "async"},
 		{EnvEndpoint: "c:1", EnvHeaders: "novalue"},
+		{EnvRequired: "true"},                                   // mandatory audit with no endpoint
+		{EnvRequired: "yes please"},                             // unparseable
+		{EnvRequired: "1", "GOPHERAGENT_AUDIT_ENDPIONT": "c:1"}, // the typo REQUIRED exists to catch
 	} {
 		if _, _, err := configFromEnv(env(bad)); err == nil {
 			t.Fatalf("invalid env %v accepted", bad)
 		}
 	}
+	if _, ok, err := configFromEnv(env(map[string]string{EnvRequired: "false"})); ok || err != nil {
+		t.Fatalf("REQUIRED=false without endpoint must just be off: ok=%v err=%v", ok, err)
+	}
 	if cfg, _, _ := configFromEnv(env(map[string]string{EnvEndpoint: "c:1"})); cfg.ServiceName != "gopheragent" || cfg.DefaultTenantID != "default" {
 		t.Fatalf("defaults: service=%q tenant=%q", cfg.ServiceName, cfg.DefaultTenantID)
 	}
@@ -135,3 +146,51 @@ func TestInstrument_SingleTenantNeedsNoActor(t *testing.T) {
 		t.Fatal("record not attributed to the default tenant")
 	}
 }
+
+// TestFromEnv_HealthMetricsUseGlobalMeter: with OTel enabled globally, the
+// env-built client reports its own health with no extra wiring.
+func TestFromEnv_HealthMetricsUseGlobalMeter(t *testing.T) {
+	reader := sdkmetric.NewManualReader()
+	prev := otel.GetMeterProvider()
+	otel.SetMeterProvider(sdkmetric.NewMeterProvider(sdkmetric.WithReader(reader)))
+	t.Cleanup(func() { otel.SetMeterProvider(prev) })
+
+	t.Setenv(EnvEndpoint, startGRPCReceiver(t, &logsReceiver{}))
+	t.Setenv(EnvInsecure, "true")
+	c, err := FromEnv(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer c.Close(context.Background())
+	if err := c.Send(context.Background(), sampleEvent); err != nil {
+		t.Fatal(err)
+	}
+	var rm metricdata.ResourceMetrics
+	if err := reader.Collect(context.Background(), &rm); err != nil {
+		t.Fatal(err)
+	}
+	for _, sm := range rm.ScopeMetrics {
+		for _, m := range sm.Metrics {
+			if m.Name == "gopheragent.audit.records" {
+				return
+			}
+		}
+	}
+	t.Fatal("FromEnv client recorded no health metrics on the global meter")
+}
+
+func TestInstrument_WarnsAboutToolsRegisteredAfterIt(t *testing.T) {
+	var buf strings.Builder
+	prev := log.Writer()
+	log.SetOutput(&buf)
+	t.Cleanup(func() { log.SetOutput(prev) })
+
+	c := newTestClient(t, Config{Endpoint: startGRPCReceiver(t, &logsReceiver{}), Insecure: true, DefaultTenantID: "d"})
+	loop := agent.New(history.NewInMemSessionManager("sys"), tools.NewRegistry(), &scriptLLM{})
+	c.Instrument(loop)
+	loop.Tools.Register(&stubTool{name: "refund"})
+	_, _ = loop.RunIteration(context.Background(), "s", "q")
+	if !strings.Contains(buf.String(), "auditlog: [tool refund] attached after Instrument") {
+		t.Fatalf("no late-registration warning: %q", buf.String())
+	}
+}
diff --git a/pkg/telemetry/otelsetup/instrument.go b/pkg/telemetry/otelsetup/instrument.go
index 24ec992..a53f695 100644
--- a/pkg/telemetry/otelsetup/instrument.go
+++ b/pkg/telemetry/otelsetup/instrument.go
@@ -1,6 +1,7 @@
 package otelsetup
 
 import (
+	"github.com/hung12ct/gopheragent/internal/latewire"
 	"github.com/hung12ct/gopheragent/pkg/agent"
 	"github.com/hung12ct/gopheragent/pkg/telemetry/otelllm"
 	"github.com/hung12ct/gopheragent/pkg/telemetry/oteltools"
@@ -14,7 +15,8 @@ import (
 //	tel.Instrument(loop, otelllm.WithSystem("anthropic"), otelllm.WithModel(model))
 //
 // Call it once the loop is configured and its tools are registered; tools
-// registered later are not instrumented. Calling it twice is harmless. When
+// registered later are not instrumented (a warning names them on the loop's
+// first event). Calling it twice is harmless. When
 // telemetry is disabled (no endpoint configured) it changes nothing, so it is
 // safe to call unconditionally. Returns loop for chaining.
 //
@@ -25,6 +27,7 @@ func (p *Providers) Instrument(loop *agent.AgentLoop, llmOpts ...otelllm.Option)
 	if p == nil || !p.Enabled || loop == nil {
 		return loop
 	}
+	latewire.Watch(loop, "otelsetup", false)
 	loop.Configure(agent.WithTracer(p.Tracer), agent.WithMeter(p.Meter))
 	if loop.LLM != nil {
 		opts := append([]otelllm.Option{otelllm.WithTracer(p.Tracer), otelllm.WithMeter(p.Meter)}, llmOpts...)