Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

docs: name Beacon Managed MCP as a downstream consumer of the schema

Claude3e72551351b1
diff --git a/docs/security/retention-redaction.mdx b/docs/security/retention-redaction.mdx
index 883c76fc..53511e47 100644
--- a/docs/security/retention-redaction.mdx
+++ b/docs/security/retention-redaction.mdx
@@ -81,6 +81,15 @@ transform that removes retained text, tool arguments/results, command output,
raw fields, diffs, inventory content, and MCP definitions before buffering or
upload while preserving stable metadata, hashes, counts, and token usage.
+The per-string limit also bounds what Beacon Managed MCP can search. Each retained
+string is capped at 4 KB (`DefaultStringLimit` in `pkg/asymptoteobserve/privacy.go`)
+before it is written, so text past that point in a long tool output, command output,
+or diff is never forwarded and Beacon Managed grep cannot match it; the event carries
+`field_truncated` and `content.truncated` instead. The limit is intentional and is
+not raised for search. Metadata-only forwarding removes the content that Beacon
+Managed grep searches, so for those endpoints its grep and read return little. See
+[Downstream consumers](/telemetry-schema/normalization#downstream-consumers).
+
Review runtime scope, artifact access, destination permissions, and downstream retention before rollout so retained content matches your approved telemetry policy.
## Related
diff --git a/docs/telemetry-schema/normalization.mdx b/docs/telemetry-schema/normalization.mdx
index a5408074..a125102b 100644
--- a/docs/telemetry-schema/normalization.mdx
+++ b/docs/telemetry-schema/normalization.mdx
@@ -232,6 +232,40 @@ approval hook, Beacon emits an `approval.allowed` event carrying `approval.requi
approval-shaped detections have something to match. Nothing was gated there, so those events are
`inferred`.
+## Downstream consumers
+
+Beacon Managed MCP searches and reads the session history an endpoint forwards to Beacon Managed,
+and it works from this normalized schema. A schema change can therefore change what Beacon Managed
+search finds, in three ways:
+
+1. **Searchable fields.** Beacon Managed grep searches these fields: `prompt`, `message`,
+ `gen_ai.{input,output,system_instructions,tool,retrieval}`, `tool`, `command`, `file`, `mcp`,
+ `approval`, `policy`, `error`, and `health`. Content in a new field is forwarded and stored, but
+ grep does not find it until Beacon Managed searches that field too.
+2. **Event types and message shapes.** Beacon Managed presents events the way the local trace view
+ (`internal/endpoint/dashboard/traces.go`) does. A new event type or message shape appears there
+ as a generic event until Beacon Managed supports it.
+3. **Harness names.** Beacon Managed groups sessions by the canonical names `NormalizeHarnessName`
+ in `pkg/asymptoteobserve/harness.go` produces. A new harness or spelling is grouped correctly in
+ Beacon Managed only once Beacon Managed knows it too.
+
+Release a change to any of these together with the matching Beacon Managed change.
+
+### What Beacon Managed grep cannot see
+
+Two limits on what Beacon Managed grep and read return come from the endpoint, and both are intended:
+
+- **Per-string limit.** `DefaultStringLimit = 4096` in `pkg/asymptoteobserve/privacy.go` caps each
+ retained string before it is written. Text past the first 4 KB of a long tool output, command
+ output, or diff is never written locally, so it is never forwarded and Beacon Managed grep cannot
+ match it. The event records the cut with `field_truncated` and `content.truncated`. This trades
+ completeness for privacy and a bounded event size; see
+ [Redaction and size limits](/security/retention-redaction).
+- **Metadata-only forwarding.** An endpoint connected to Beacon Managed in Metadata-only mode
+ removes prompts, responses, reasoning, tool arguments and results, command output, and diffs
+ before upload. Those are the fields grep searches, so for such endpoints Beacon Managed grep and
+ read return little beyond identifiers, counts, and token usage.
+
## Related
<Columns cols={2}>
diff --git a/pkg/asymptoteobserve/harness.go b/pkg/asymptoteobserve/harness.go
index afb589af..9f5f8eee 100644
--- a/pkg/asymptoteobserve/harness.go
+++ b/pkg/asymptoteobserve/harness.go
@@ -21,6 +21,10 @@ import "strings"
//
// Ordering matters. The browser-chat cases must precede the generic "claude" rule, which would
// otherwise coerce claude_web into claude_code.
+//
+// Beacon Managed groups forwarded sessions by these canonical names, so a new harness or spelling
+// here needs a matching Beacon Managed change in the same release; see "Downstream consumers" in
+// docs/telemetry-schema/normalization.mdx.
func NormalizeHarnessName(name string) string {
lower := strings.ToLower(strings.TrimSpace(name))
switch {