feat(utee): Phase 1 observability pass-through adapter layer#46
Merged
dgarson merged 3 commits intoobservability/mainfrom Feb 22, 2026
Merged
feat(utee): Phase 1 observability pass-through adapter layer#46dgarson merged 3 commits intoobservability/mainfrom
dgarson merged 3 commits intoobservability/mainfrom
Conversation
Implements UTEE Phase 1 with the following scope: - Observability pass-through adapter layer for tool execution - Auto-generate/propagate requestId + traceId/spanId metadata - Structured logs for tool invocations - Basic metrics hooks/counters (invocation count, error count, duration) - Feature flag to enable/disable Phase 1 path Guardrails maintained: - No behavior changes to existing tool result/error payloads - No retry/idempotency/capability negotiation - Minimal blast radius (additive only) - Rollback switch works (utee.enabled config flag) Files added: - src/agents/utee-adapter.ts: Core UTEE adapter implementation - src/agents/utee-init.ts: Config initialization - src/agents/utee-adapter.test.ts: Unit tests (26 tests passing) - src/config/types.utee.ts: UTEE config types - src/config/zod-schema.utee.ts: UTEE zod schema Files modified: - src/agents/pi-tool-definition-adapter.ts: Integrate UTEE wrapper - src/config/types.openclaw.ts: Add utee config property - src/config/zod-schema.ts: Add UTEE schema import and field
Fixes from architectural review:
1. Feature-flag bug at tool wrapping site:
- Changed pi-tool-definition-adapter.ts to always wrap tools with UTEE
- Wrapper now checks isUteeEnabled() at invocation time, not definition time
- This fixes runtime enable-after-start scenarios
2. Config init not wired into runtime:
- Added initUteeFromConfig() call in gateway startup (server.impl.ts)
- Added updateUteeFromConfig() call in config hot reload (server-reload-handlers.ts)
- Added 'utee' prefix to config reload rules (kind: none, no restart needed)
3. AsyncLocalStorage loading unreliable in ESM:
- Replaced dynamic require('async_hooks') with createRequire pattern
- Uses node:module createRequire for synchronous loading in ESM
- Maintains graceful fallback for non-Node environments
4. Phase-1 blast radius check:
- Diff is minimal: 6 files, 83 insertions, 14 deletions
- Added 2 new tests proving runtime toggle works correctly
Tests: 28 tests pass including 2 new runtime toggle tests
- Move createRequire import to top-level ESM imports - Use node:async_hooks protocol for consistency - Avoids undefined require in pure ESM environments
Owner
Author
|
Tim architecture review complete — sign-off granted for UTEE Phase 1. ✅ Blocking issues from prior review are resolved:
✅ Guardrails still hold:
✅ Local validation in
From architecture perspective: ready for 5%/48h canary once CI is green. |
dgarson
added a commit
that referenced
this pull request
Feb 22, 2026
…Editor (Piper) AgentScheduler: 7 seed schedules, list+calendar toggle, master/detail, run now/edit/delete TokenLedger: 10 ledger entries, cost by agent+model breakdown, 7-day bar chart ThemeEditor (Piper): preset themes, live preview panel, CSS var export; fixed TS errors Sprint total: 47 views
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements UTEE (Unified Tool Execution Envelope) Phase 1: observability pass-through adapter.
All 3 blocking issues from Tim's Phase 1 review have been resolved:
should wrap tools created while disabled and pick up enable later)initUteeFromConfigwired inserver.impl.ts;updateUteeFromConfigwired inserver-reload-handlers.tsimport()fallback patternWhat's in Phase 1 (strictly pass-through)
requestIdandtraceIdper invocationutee_tool_invocation,utee_tool_resultuteeEnabled = false)enableUtee()/disableUtee()What is NOT in Phase 1
Test Results
28/28 tests passing:
Critical tests:
should start disabled✅should pass through when UTEE is disabled✅should wrap tools created while disabled and pick up enable later✅ (runtime toggle fix)should add minimal overhead when enabled (<1ms per call)✅Rollout Plan (from canary readiness doc)
Phase 1 canary: 5% of sessions / 48h
Rollback: set
utee.enabled = false, hot-reloads without restartSuccess criteria: P95 latency overhead <5ms, no error rate increase
Files Changed
src/agents/utee-adapter.ts(547 lines) — main adaptersrc/agents/utee-init.ts(33 lines) — config initializationsrc/agents/utee-adapter.test.ts(381 lines) — test suitesrc/agents/pi-tool-definition-adapter.ts— tool wrapping integrationsrc/config/types.utee.ts— config typessrc/config/zod-schema.utee.ts— config schemasrc/gateway/server.impl.ts— startup wiringsrc/gateway/server-reload-handlers.ts— hot-reload wiringsrc/gateway/config-reload.ts— reload ruleCanary readiness doc:
sandy/utee-phase1-canary-readiness.mdSpec:
tim/memory/2026-02-21-utee-notes.md