docs(compass-agent): loop-OTel deployer contract + env reachability pin (RIG-2508 T2) - #654
Open
rigel-mintaka wants to merge 2 commits into
Open
docs(compass-agent): loop-OTel deployer contract + env reachability pin (RIG-2508 T2)#654rigel-mintaka wants to merge 2 commits into
rigel-mintaka wants to merge 2 commits into
Conversation
|
Compass engineering docs preview: https://compass-agent-rig-2508-loop-smmr.compass-eng-docs.pages.dev Deployed from Changed pages: |
Base automatically changed from
compass-agent/rig-2508-loop-otel-activate
to
main
August 26, 2026 14:44
…in (RIG-2508 T2) T2 of the frozen loop-OTel record. Two additive deliverables, no production code-path change beyond T1. - Env reachability test (cli.test.ts): pins that all four loop-OTel keys the Runner materializes into $HOME/.compass/env -- OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_RESOURCE_ATTRIBUTES, OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT -- survive isReservedEnvKey filtering (none are HOME/COMPASS_*) and reach process.env before the registration point (cli.ts:838), via the env-merge loop (cli.ts:614-618) that runs earlier. Non-vacuous: a COMPASS_-prefixed or HOME key would be dropped, as the neighboring test pins for COMPASS_FUTURE_VAR. - deployer-contract.md: maintainer-facing reference for configuring a collector -- endpoint key, service-name override, content-capture opt-in + sensitivity warning, off-by-default guarantee, and the two asymmetries a deployer must know: F5 endpoint-gate (the loop honors OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, the transport gates only on OTEL_EXPORTER_OTLP_ENDPOINT) and F1 service-name split (an OTEL_SERVICE_NAME override renames the loop signal only; the durable cross-signal join is compass.session.id, not service.name). All cites source-verified against @oh-my-pi/pi-coding-agent@16.5.2 and the frozen transport otel-layer.ts. Doc lives under docs/designs/platform/ (ungoverned ledger root -> no DECISIONS row). Stacked on #648 (T1). Co-authored-by: Matt Wilkinson <matt@rigel.build>
…ct sentinel (RIG-2508 T2) The four-key loop-OTel reachability test wrote OTEL_SERVICE_NAME=compass-agent, which is byte-identical to the activation's `??=` default (cli.ts:839). A filter-drop regression (key wrongly reserved by isReservedEnvKey) would re-default to the same value, leaving the assertion green. Swap to a distinct sentinel (deployer-custom-name) so the key must genuinely survive the filter and reach process.env for the assertion to pass; proven to red under a simulated reserve of OTEL_SERVICE_NAME. The other three keys were already non-vacuous. Co-authored-by: Matt Wilkinson <matt@rigel.build>
rigel-mintaka
force-pushed
the
compass-agent/rig-2508-loop-otel-deployer-contract
branch
from
August 26, 2026 14:51
6ccc0fd to
5db3779
Compare
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.
T2 of the frozen loop-OTel record. Two additive deliverables, no
production code-path change beyond T1.
the Runner materializes into $HOME/.compass/env -- OTEL_SERVICE_NAME,
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_RESOURCE_ATTRIBUTES,
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT -- survive
isReservedEnvKey filtering (none are HOME/COMPASS_*) and reach
process.env before the registration point (cli.ts:838), via the
env-merge loop (cli.ts:614-618) that runs earlier. Non-vacuous: a
COMPASS_-prefixed or HOME key would be dropped, as the neighboring test
pins for COMPASS_FUTURE_VAR.
collector -- endpoint key, service-name override, content-capture
opt-in + sensitivity warning, off-by-default guarantee, and the two
asymmetries a deployer must know: F5 endpoint-gate (the loop honors
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, the transport gates only on
OTEL_EXPORTER_OTLP_ENDPOINT) and F1 service-name split (an
OTEL_SERVICE_NAME override renames the loop signal only; the durable
cross-signal join is compass.session.id, not service.name). All cites
source-verified against @oh-my-pi/pi-coding-agent@16.5.2 and the frozen
transport otel-layer.ts.
Doc lives under docs/designs/platform/ (ungoverned ledger root -> no
DECISIONS row). Stacked on #648 (T1).
Co-authored-by: Matt Wilkinson matt@rigel.build