Skip to content

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

Upload shared traces as a trace.v1 summary and its events

Claudec74d0b1ff762
diff --git a/CLAUDE.md b/CLAUDE.md
index deddc554..944ece6e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -26,7 +26,7 @@ Do not recreate or depend on removed `asymptote` mirror trees. Keep new work foc
- Beacon is visibility-first endpoint telemetry for local AI agent runtimes, not a hosted policy service or general endpoint protection product.
- Preserve the local-only default. The public Beacon build must not require a hosted account, remote policy fetch, hosted dashboard, or external network dependency during normal hook execution, and hooks themselves never touch the network.
-- `beacon login` is the account-identity channel for interactive users and is required by the interactive `beacon endpoint install` wizard. It uses browser PKCE against beacon.sh and stores the scoped CLI token only in `~/.beacon/auth/session.json` (0600 under a 0700 directory). Signing in alone never starts forwarding. User-mode `beacon endpoint connect` may send that token once to `POST /api/cli/enroll/account` to authorize minting a separate device ingest key, and `beacon mcp token create` may send it to `POST /api/cli/mcp/tokens` (scope `mcp:token:create`, listed on the sign-in page) to mint a personal MCP token that is printed once to stdout and never written to a file, and `beacon share` may send it (scope `traces:write`, also on the sign-in page) to `PUT /v1/traces/{external_id}`, `POST /v1/traces/{external_id}/messages/batch` and `GET /v1/traces/{external_id}` on the session's own base URL to upload a shared trace the person chose to publish (`cli/beacon/internal/account/share.go`; a `bcn_api_` API key from `--key` or `BEACON_API_KEY` may stand in for it, precedence `--key`, then a current sign-in carrying the scope, then the environment). These are explicit, user-initiated requests with redirects refused; hooks, plugins and background jobs never make them. Never copy the account token into endpoint config, Vector, hook environments, logs, or command output. System/root/package/MDM/CI/piped-stdin/dry-run installs stay noninteractive and account-free.
+- `beacon login` is the account-identity channel for interactive users and is required by the interactive `beacon endpoint install` wizard. It uses browser PKCE against beacon.sh and stores the scoped CLI token only in `~/.beacon/auth/session.json` (0600 under a 0700 directory). Signing in alone never starts forwarding. User-mode `beacon endpoint connect` may send that token once to `POST /api/cli/enroll/account` to authorize minting a separate device ingest key, and `beacon mcp token create` may send it to `POST /api/cli/mcp/tokens` (scope `mcp:token:create`, listed on the sign-in page) to mint a personal MCP token that is printed once to stdout and never written to a file, and `beacon share` may send it (scope `traces:write`, also on the sign-in page) to `PUT /v1/traces/{external_id}`, `POST /v1/traces/{external_id}/events/batch` and `GET /v1/traces/{external_id}` on the session's own base URL to upload a shared trace the person chose to publish, as a `beacon.trace.v1` summary and its events (`cli/beacon/internal/account/share.go`; a `bcn_api_` API key from `--key` or `BEACON_API_KEY` may stand in for it, precedence `--key`, then a current sign-in carrying the scope, then the environment). These are explicit, user-initiated requests with redirects refused; hooks, plugins and background jobs never make them. Never copy the account token into endpoint config, Vector, hook environments, logs, or command output. System/root/package/MDM/CI/piped-stdin/dry-run installs stay noninteractive and account-free.
- Beacon Cloud forwarding (`cli/beacon/internal/endpoint/asymptote`, `beacon endpoint connect`, `beacon endpoint asymptote`) is Vector-shaped: Beacon writes local JSONL, Vector ships runtime lines only from the connection point forward and reads inventory from the beginning to establish the endpoint's current baseline, plus the one bounded exception of the session backfill (below), and the `bcn_device_*` key stays only in `<BaseDir>/asymptote/vector-secrets.json` via Vector's secret backend. The onboarding wizard preselects Beacon Cloud, and confirming it connects this endpoint in the same command once the local install has succeeded; an endpoint that is already enrolled is never re-enrolled, because enrollment rotates the device key. Standard mode ships locally sanitized retained content; metadata-only uses local Vector transforms to remove prompts, responses, reasoning, tool arguments/results, command output, raw fields, diffs, inventory content, and MCP definitions before buffering/upload. Keep the ingest URL `https://`, the wire contract aligned with `beacon-ingest` (`/v1/ingest/{runtime,inventory}` and `/v1/ingest/health`), and do not add another endpoint network channel. The cloud-sandbox shuttle is the bounded exception: only with `BEACON_ORIGIN=cloud`, it can upload new runtime lines to GCS, S3, or the same Beacon ingest contract because no Vector/service manager/browser/persistent disk exists there.
- Session backfill (`cli/beacon/cmd/endpoint_backfill.go`; docs in `docs/cli/endpoint-install.mdx#session-backfill` and `docs/cli/endpoint-connect.mdx#session-backfill`): after every successful install (user or system mode), every session-store collector runs once with `CollectOptions.Since` (30 days; `sessionwindow.Recent` keeps those sessions, newest first, and never touches the cursors of the rest) and a shared `writer.Budget` (24 MiB, at most 12 MiB per runtime through `Budget.Sub`; a refused append returns `writer.ErrBudgetSpent`, the collector stops with cursors past only what was written, and a manual sync reads the rest). A new session-store collector takes both fields and joins `endpointBackfillRunners`. Every connect, first or re-connect, user or system, runs the same sweep before enrollment (skipped when install just ran it) and, before the forwarder starts, `asymptote.StageBackfill` copies the window's `harness.collection_method=poll` lines into `cloud-backfill.jsonl` beside the runtime log, which the `beacon_backfill` Vector source (fingerprinted `device_and_inode`, so each atomically restaged copy is a new file) reads from the beginning into the runtime sink through the same privacy transform. Live hook/OTLP/plugin history before the connection point stays local. Re-connects restage, so a resend of already-shipped lines is expected and rests on the deterministic `event.id`; a privacy-mode change clears the checkpoints and the restage renames the new-mode copy over the old one (kept until then so the copy is always a new inode; deleted instead when nothing restages), and `disconnect` removes it. System mode runs the collectors under `withUserHome` for the active console user (`activeConsoleUser`), with cursors under the system base directory, and reports a skip when nobody is logged in. The wizard's confirm screen names the upload (`WizardOptions.BackfillDays`). Dry-run, `--no-backfill` and `BEACON_BACKFILL=0` skip all of it; the cmd tests run with `BEACON_BACKFILL=0` set in `TestMain`.
- `beacon endpoint install` has a full-screen onboarding wizard on interactive user TTYs. It signs in, preselects Beacon Cloud, requires an explicit choice to opt out to Local, and asks Managed users to choose Standard or Metadata-only privacy. Signing in alone still moves no telemetry. Confirming Beacon Cloud does: the confirm screen states that it installs Beacon and starts forwarding, and names what the selected privacy mode sends, so that screen is the consent point. The managed destination is recorded only after enrollment succeeds, so a failed enrollment leaves a working local install, prints `beacon endpoint connect` as the retry, and re-offers the question on the next install. The onboarding record is written only after `lifecycle.Install` returns, because a profile written first left a failed install looking onboarded and silently skipped the wizard on the retry. Explicit `install --connect` is unchanged. The wizard is skipped for system/root/CI/piped-stdin/dry-run or `BEACON_ONBOARDING=0`; those unattended paths must never gain an account or browser dependency. Legacy `BEACON_ONBOARDING_EMAIL`/`USAGE` submissions remain only for fleet compatibility. After the destination, the wizard shows an agent tools screen; every row is preselected (opt-out, space toggles). Beacon Cloud MCP is offered only with Beacon Cloud and runs the `beacon mcp connect` flow (`connectCloudMCP` with `yes`, OAuth, detected harnesses) only after the endpoint is connected (or already was), via `finishCloudSetup`; a failed enrollment skips it and names the retry. The Beacon Agent Skills are offered for either destination and installed user-wide into `~/.agents/skills` and, when Claude Code is set up, `~/.claude/skills` (`cli/beacon/internal/agentskills`, `beacon skills install|uninstall`; a `.beacon-managed` marker decides what Beacon may replace or remove; install and repair refresh only copies Beacon already wrote). Both run after `lifecycle.Install` returns and warn rather than fail. The answers are recorded as `onboarding.cloud_mcp`/`agent_skills`. Implementation lives in `cli/beacon/internal/onboarding`, `cli/beacon/cmd/endpoint_onboarding.go`, `cli/beacon/cmd/endpoint_install.go` and `cli/beacon/cmd/agent_tools.go`; keep `docs/cli/endpoint-onboarding.mdx` and `docs/cli/skills.mdx` in sync.
diff --git a/cli/beacon/internal/account/share.go b/cli/beacon/internal/account/share.go
index 9efaef0c..d17690f0 100644
--- a/cli/beacon/internal/account/share.go
+++ b/cli/beacon/internal/account/share.go
@@ -16,9 +16,10 @@ import (
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
)
-// Shared traces: `beacon share` uploads one session's messages to beacon.sh with
-// `PUT /v1/traces/{external_id}`, `POST /v1/traces/{external_id}/messages/batch` and reads its own
-// trace back with `GET /v1/traces/{external_id}`. These are explicit, user-initiated requests; no
+// Shared traces: `beacon share` uploads one session to beacon.sh as a beacon.trace.v1 trace: its
+// summary with `PUT /v1/traces/{external_id}`, its events with
+// `POST /v1/traces/{external_id}/events/batch`, and reads its own trace back with
+// `GET /v1/traces/{external_id}`. These are explicit, user-initiated requests; no
// hook or background job ever makes them.
//
// They authorize with the signed-in CLI token when it carries ScopeTracesWrite, or with a Beacon API
@@ -184,13 +185,16 @@ func NewShareClient(cred ShareCredential, client *http.Client) (*ShareClient, er
// BaseURL is the service the client sends to.
func (c *ShareClient) BaseURL() string { return c.cred.BaseURL }
-// PutTrace creates or updates a trace's metadata.
+// PutTrace creates or updates a trace's summary and sharing settings.
func (c *ShareClient) PutTrace(ctx context.Context, externalID string, trace asymptoteobserve.ShareTraceV1) (*asymptoteobserve.ShareTraceResultV1, error) {
if trace.SchemaVersion == "" {
- trace.SchemaVersion = asymptoteobserve.ShareSchemaVersion
+ trace.SchemaVersion = asymptoteobserve.TraceSchemaVersion
}
- if strings.TrimSpace(trace.AgentID) == "" {
- return nil, errors.New("a shared trace needs an agent id")
+ if trace.SchemaVersion != asymptoteobserve.TraceSchemaVersion {
+ return nil, fmt.Errorf("unsupported trace schema %q", trace.SchemaVersion)
+ }
+ if strings.TrimSpace(trace.Summary.Harness.Name) == "" {
+ return nil, errors.New("a shared trace needs the harness that recorded it")
}
if trace.Visibility != "" && !asymptoteobserve.ValidShareVisibility(trace.Visibility) {
return nil, fmt.Errorf("unknown visibility %q", trace.Visibility)
@@ -216,44 +220,44 @@ func (c *ShareClient) PutTrace(ctx context.Context, externalID string, trace asy
return &result, nil
}
-// PutMessagesResult sums the batches PutMessages sent.
-type PutMessagesResult struct {
+// PostEventsResult sums the batches PostEvents sent.
+type PostEventsResult struct {
Batches int `json:"batches"`
- Accepted int `json:"accepted"`
- // MessageCount is the trace's total after the last batch, as beacon.sh reported it.
- MessageCount int `json:"message_count"`
+ Upserted int `json:"upserted"`
+ // EventCount is the trace's total after the last batch, as beacon.sh reported it.
+ EventCount int `json:"event_count"`
}
-// PutMessages upserts messages in batches of at most ShareMaxMessagesPerBatch messages and
-// ShareMaxBatchBytes bytes, each gzip-compressed. Re-sending a message is idempotent, so a failed
-// run can simply be repeated. An empty list sends nothing.
-func (c *ShareClient) PutMessages(ctx context.Context, externalID string, messages []asymptoteobserve.ShareMessageV1) (PutMessagesResult, error) {
- var result PutMessagesResult
- batches, err := ShareBatches(messages, asymptoteobserve.ShareMaxMessagesPerBatch, ShareMaxBatchBytes)
+// PostEvents upserts the batch's events in requests of at most ShareMaxEventsPerBatch events and
+// ShareMaxBatchBytes bytes, each gzip-compressed. Events are upserted by id, so re-sending one is
+// idempotent and a failed run can simply be repeated. An empty batch sends nothing.
+func (c *ShareClient) PostEvents(ctx context.Context, externalID string, batch asymptoteobserve.ShareEventsBatchV1) (PostEventsResult, error) {
+ var result PostEventsResult
+ batches, err := ShareBatches(batch.Events, asymptoteobserve.ShareMaxEventsPerBatch, ShareMaxBatchBytes)
if err != nil {
return result, err
}
- for _, batch := range batches {
- payload, status, err := c.do(ctx, http.MethodPost, externalID, "/messages/batch", batch.Body, true)
+ for _, request := range batches {
+ payload, status, err := c.do(ctx, http.MethodPost, externalID, "/events/batch", request.Body, true)
if err != nil {
return result, err
}
- if err := c.statusError("upload messages", status, payload); err != nil {
+ if err := c.statusError("upload events", status, payload); err != nil {
return result, err
}
- var accepted asymptoteobserve.ShareBatchResultV1
- if err := json.Unmarshal(payload, &accepted); err != nil {
+ var upserted asymptoteobserve.ShareBatchResultV1
+ if err := json.Unmarshal(payload, &upserted); err != nil {
return result, fmt.Errorf("parse batch response: %w", err)
}
result.Batches++
- result.Accepted += accepted.Accepted
- result.MessageCount = accepted.MessageCount
+ result.Upserted += upserted.Upserted
+ result.EventCount = upserted.EventCount
}
return result, nil
}
-// GetTrace reads the owner's view of a trace. found is false when beacon.sh has no such trace for
-// this credential.
+// GetTrace reads the owner's view of a trace, with the id of the last event beacon.sh holds. found
+// is false when beacon.sh has no such trace for this credential.
func (c *ShareClient) GetTrace(ctx context.Context, externalID string) (*asymptoteobserve.ShareTraceStateV1, bool, error) {
payload, status, err := c.do(ctx, http.MethodGet, externalID, "", nil, false)
if err != nil {
@@ -272,16 +276,16 @@ func (c *ShareClient) GetTrace(ctx context.Context, externalID string) (*asympto
return &state, true, nil
}
-// ShareBatch is one batch request body and how many messages it carries.
+// ShareBatch is one batch request body and how many events it carries.
type ShareBatch struct {
- Body []byte
- Messages int
+ Body []byte
+ Events int
}
-// ShareBatches splits messages into batch bodies of at most maxMessages messages and maxBytes
-// bytes. A single message larger than maxBytes is refused rather than sent to be rejected.
-func ShareBatches(messages []asymptoteobserve.ShareMessageV1, maxMessages, maxBytes int) ([]ShareBatch, error) {
- const envelope = len(`{"messages":[]}`)
+// ShareBatches splits events into ShareEventsBatchV1 bodies of at most maxEvents events and
+// maxBytes bytes. A single event larger than maxBytes is refused rather than sent to be rejected.
+func ShareBatches(events []asymptoteobserve.TraceEventV1, maxEvents, maxBytes int) ([]ShareBatch, error) {
+ const envelope = len(`{"events":[]}`)
var batches []ShareBatch
var current [][]byte
size := envelope
@@ -290,30 +294,30 @@ func ShareBatches(messages []asymptoteobserve.ShareMessageV1, maxMessages, maxBy
return
}
body := make([]byte, 0, size)
- body = append(body, `{"messages":[`...)
- for i, m := range current {
+ body = append(body, `{"events":[`...)
+ for i, e := range current {
if i > 0 {
body = append(body, ',')
}
- body = append(body, m...)
+ body = append(body, e...)
}
body = append(body, `]}`...)
- batches = append(batches, ShareBatch{Body: body, Messages: len(current)})
+ batches = append(batches, ShareBatch{Body: body, Events: len(current)})
current, size = nil, envelope
}
- for _, message := range messages {
- encoded, err := json.Marshal(message)
+ for _, event := range events {
+ encoded, err := json.Marshal(event)
if err != nil {
return nil, err
}
if envelope+len(encoded) > maxBytes {
- return nil, fmt.Errorf("message %s is %d bytes, more than one batch may carry", message.ID, len(encoded))
+ return nil, fmt.Errorf("event %s is %d bytes, more than one batch may carry", event.ID, len(encoded))
}
extra := len(encoded)
if len(current) > 0 {
extra++ // the comma
}
- if len(current) >= maxMessages || size+extra > maxBytes {
+ if len(current) >= maxEvents || size+extra > maxBytes {
flush()
extra = len(encoded)
}
diff --git a/cli/beacon/internal/account/share_test.go b/cli/beacon/internal/account/share_test.go
index 4112d565..7028b9f3 100644
--- a/cli/beacon/internal/account/share_test.go
+++ b/cli/beacon/internal/account/share_test.go
@@ -105,7 +105,7 @@ type shareServer struct {
mu sync.Mutex
server *httptest.Server
auth []string
- batches [][]asymptoteobserve.ShareMessageV1
+ batches [][]asymptoteobserve.TraceEventV1
encoding []string
trace *asymptoteobserve.ShareTraceV1
paths []string
@@ -127,8 +127,8 @@ func newShareServer(t *testing.T) *shareServer {
}
s.trace = &trace
w.WriteHeader(http.StatusCreated)
- fmt.Fprint(w, `{"id":"k3x","external_id":"claude_code:abc","url":"https://beacon.sh/s/k3x","visibility":"direct","message_count":0,"created":true}`)
- case r.Method == http.MethodPost && r.URL.Path == "/v1/traces/claude_code:abc/messages/batch":
+ fmt.Fprint(w, `{"id":"k3x","external_id":"claude_code:abc","url":"https://beacon.sh/s/k3x","visibility":"direct","event_count":0,"created":true}`)
+ case r.Method == http.MethodPost && r.URL.Path == "/v1/traces/claude_code:abc/events/batch":
s.encoding = append(s.encoding, r.Header.Get("Content-Encoding"))
var body io.Reader = r.Body
if r.Header.Get("Content-Encoding") == "gzip" {
@@ -139,19 +139,19 @@ func newShareServer(t *testing.T) *shareServer {
}
body = zr
}
- var batch asymptoteobserve.ShareMessagesBatchV1
+ var batch asymptoteobserve.ShareEventsBatchV1
if err := json.NewDecoder(body).Decode(&batch); err != nil {
http.Error(w, err.Error(), 400)
return
}
- s.batches = append(s.batches, batch.Messages)
+ s.batches = append(s.batches, batch.Events)
total := 0
for _, b := range s.batches {
total += len(b)
}
- fmt.Fprintf(w, `{"accepted":%d,"message_count":%d}`, len(batch.Messages), total)
+ fmt.Fprintf(w, `{"upserted":%d,"event_count":%d}`, len(batch.Events), total)
case r.Method == http.MethodGet && r.URL.Path == "/v1/traces/claude_code:abc":
- fmt.Fprint(w, `{"id":"k3x","url":"https://beacon.sh/s/k3x","visibility":"direct","message_count":2,"last_message_id":"m2","max_order":2}`)
+ fmt.Fprint(w, `{"id":"k3x","url":"https://beacon.sh/s/k3x","visibility":"direct","event_count":2,"last_event_id":"e2","max_number":2}`)
default:
http.Error(w, `{"detail":"no such trace"}`, http.StatusNotFound)
}
@@ -160,18 +160,21 @@ func newShareServer(t *testing.T) *shareServer {
return s
}
-func messagesN(n int, textBytes int) []asymptoteobserve.ShareMessageV1 {
- out := make([]asymptoteobserve.ShareMessageV1, n)
+func eventsN(n int, textBytes int) []asymptoteobserve.TraceEventV1 {
+ out := make([]asymptoteobserve.TraceEventV1, n)
for i := range out {
- out[i] = asymptoteobserve.ShareMessageV1{
- ID: fmt.Sprintf("m%d", i+1), Order: i + 1, Role: "user", Timestamp: "2026-10-01T00:00:00Z",
- Text: strings.Repeat("x", textBytes),
- Parts: []asymptoteobserve.SharePartV1{{Type: "text", Order: 1, Content: asymptoteobserve.ShareTextContent{Text: "x"}}},
+ out[i] = asymptoteobserve.TraceEventV1{
+ ID: fmt.Sprintf("e%d", i+1), Number: i + 1, Type: "user_message", Action: "prompt.submitted", Timestamp: "2026-10-01T00:00:00Z",
+ Content: &asymptoteobserve.TraceContentV1{Text: strings.Repeat("x", textBytes), Retention: "full", Included: true},
}
}
return out
}
+func shareTrace(visibility string) asymptoteobserve.ShareTraceV1 {
+ return asymptoteobserve.ShareTraceV1{Summary: asymptoteobserve.TraceSummaryV1{Harness: asymptoteobserve.TraceHarnessV1{Name: "claude_code"}}, Visibility: visibility}
+}
+
func TestShareClientPutGetAndBatches(t *testing.T) {
s := newShareServer(t)
client, err := NewShareClient(shareCred(s.server.URL), s.server.Client())
@@ -179,22 +182,22 @@ func TestShareClientPutGetAndBatches(t *testing.T) {
t.Fatal(err)
}
ctx := context.Background()
- result, err := client.PutTrace(ctx, "claude_code:abc", asymptoteobserve.ShareTraceV1{AgentID: "claude_code", Visibility: "direct"})
+ result, err := client.PutTrace(ctx, "claude_code:abc", shareTrace("direct"))
if err != nil {
t.Fatalf("PutTrace: %v", err)
}
- if result.ID != "k3x" || !result.Created || s.trace.SchemaVersion != asymptoteobserve.ShareSchemaVersion {
+ if result.ID != "k3x" || !result.Created || s.trace.SchemaVersion != asymptoteobserve.TraceSchemaVersion {
t.Fatalf("result = %+v trace = %+v", result, s.trace)
}
- put, err := client.PutMessages(ctx, "claude_code:abc", messagesN(2500, 10))
+ put, err := client.PostEvents(ctx, "claude_code:abc", asymptoteobserve.ShareEventsBatchV1{Events: eventsN(2500, 10)})
if err != nil {
- t.Fatalf("PutMessages: %v", err)
+ t.Fatalf("PostEvents: %v", err)
}
- if put.Batches != 3 || put.Accepted != 2500 || put.MessageCount != 2500 {
+ if put.Batches != 3 || put.Upserted != 2500 || put.EventCount != 2500 {
t.Fatalf("put = %+v", put)
}
- if len(s.batches[0]) != 1000 || len(s.batches[2]) != 500 || s.batches[2][499].ID != "m2500" {
+ if len(s.batches[0]) != 1000 || len(s.batches[2]) != 500 || s.batches[2][499].ID != "e2500" {
t.Fatalf("batch sizes = %d %d %d", len(s.batches[0]), len(s.batches[1]), len(s.batches[2]))
}
for _, encoding := range s.encoding {
@@ -204,7 +207,7 @@ func TestShareClientPutGetAndBatches(t *testing.T) {
}
state, found, err := client.GetTrace(ctx, "claude_code:abc")
- if err != nil || !found || state.LastMessageID != "m2" || state.MaxOrder != 2 {
+ if err != nil || !found || state.LastEventID != "e2" || state.MaxNumber != 2 {
t.Fatalf("GetTrace = %+v %v %v", state, found, err)
}
if _, found, err := client.GetTrace(ctx, "claude_code:missing"); err != nil || found {
@@ -215,13 +218,13 @@ func TestShareClientPutGetAndBatches(t *testing.T) {
t.Fatalf("authorization = %q", auth)
}
}
- if _, err := client.PutMessages(ctx, "bad id!", messagesN(1, 1)); err == nil {
+ if _, err := client.PostEvents(ctx, "bad id!", asymptoteobserve.ShareEventsBatchV1{Events: eventsN(1, 1)}); err == nil {
t.Fatal("expected an invalid external id to be refused")
}
}
func TestShareBatchesHonorTheByteLimit(t *testing.T) {
- batches, err := ShareBatches(messagesN(10, 1000), 1000, 3500)
+ batches, err := ShareBatches(eventsN(10, 1000), 1000, 3500)
if err != nil {
t.Fatal(err)
}
@@ -230,17 +233,17 @@ func TestShareBatchesHonorTheByteLimit(t *testing.T) {
if len(b.Body) > 3500 {
t.Fatalf("batch of %d bytes exceeds the limit", len(b.Body))
}
- var decoded asymptoteobserve.ShareMessagesBatchV1
- if err := json.Unmarshal(b.Body, &decoded); err != nil || len(decoded.Messages) != b.Messages {
+ var decoded asymptoteobserve.ShareEventsBatchV1
+ if err := json.Unmarshal(b.Body, &decoded); err != nil || len(decoded.Events) != b.Events {
t.Fatalf("batch does not decode: %v", err)
}
- total += b.Messages
+ total += b.Events
}
if total != 10 || len(batches) < 4 {
- t.Fatalf("batches = %d, messages = %d", len(batches), total)
+ t.Fatalf("batches = %d, events = %d", len(batches), total)
}
- if _, err := ShareBatches(messagesN(1, 5000), 1000, 3500); err == nil {
- t.Fatal("expected an oversized message to be refused")
+ if _, err := ShareBatches(eventsN(1, 5000), 1000, 3500); err == nil {
+ t.Fatal("expected an oversized event to be refused")
}
if batches, err := ShareBatches(nil, 1000, 3500); err != nil || len(batches) != 0 {
t.Fatalf("empty input = %v %v", batches, err)
@@ -259,7 +262,7 @@ func TestShareClientRefusesRedirects(t *testing.T) {
if err != nil {
t.Fatal(err)
}
- _, err = client.PutTrace(context.Background(), "claude_code:abc", asymptoteobserve.ShareTraceV1{AgentID: "claude_code"})
+ _, err = client.PutTrace(context.Background(), "claude_code:abc", shareTrace(""))
if err == nil || !strings.Contains(err.Error(), "redirect") {
t.Fatalf("err = %v", err)
}
@@ -291,7 +294,7 @@ func TestShareClientMapsAuthFailures(t *testing.T) {
if err != nil {
t.Fatal(err)
}
- _, err = client.PutTrace(context.Background(), "claude_code:abc", asymptoteobserve.ShareTraceV1{AgentID: "claude_code"})
+ _, err = client.PutTrace(context.Background(), "claude_code:abc", shareTrace(""))
server.Close()
if err == nil {
t.Fatalf("%d/%s: expected an error", tc.status, tc.source)
@@ -307,3 +310,18 @@ func TestShareClientMapsAuthFailures(t *testing.T) {
}
}
}
+
+func TestShareClientRefusesAnotherSchema(t *testing.T) {
+ client, err := NewShareClient(shareCred("https://beacon.example.com"), nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ trace := shareTrace("direct")
+ trace.SchemaVersion = "beacon.share.v1"
+ if _, err := client.PutTrace(context.Background(), "claude_code:abc", trace); err == nil || !strings.Contains(err.Error(), "schema") {
+ t.Fatalf("err = %v", err)
+ }
+ if _, err := client.PutTrace(context.Background(), "claude_code:abc", asymptoteobserve.ShareTraceV1{}); err == nil {
+ t.Fatal("expected a trace without a harness to be refused")
+ }
+}
diff --git a/docs/cli/account-auth.mdx b/docs/cli/account-auth.mdx
index 8ab61b3d..45a2389e 100644
--- a/docs/cli/account-auth.mdx
+++ b/docs/cli/account-auth.mdx
@@ -98,7 +98,7 @@ The CLI uses the versioned `2026-09-01` grant contract:
- `GET /cli/auth?state=...&port=...&scopes=...` authenticates the person, lists every requested scope (space-separated in `scopes`), and redirects to the loopback callback with `state` and a one-time `exchange_code`.
- `POST /api/cli/auth/exchange` accepts the exchange code, state, and PKCE verifier. It returns a scoped access token, expiry, user identity, organization memberships, and optional active organization.
- `POST /api/cli/mcp/tokens` accepts `{"name": ..., "expires_in_days": ...}` with the access token as a Bearer credential and returns a personal Beacon Cloud MCP token (`token`, `access_token` metadata, `mcp_url`). It requires `mcp:token:create`.
-- `PUT /v1/traces/{external_id}`, `POST /v1/traces/{external_id}/messages/batch` and `GET /v1/traces/{external_id}` create, fill and read back a shared trace for `beacon share`, with the access token (or a `bcn_api_` API key) as a Bearer credential. They require `traces:write`.
+- `PUT /v1/traces/{external_id}`, `POST /v1/traces/{external_id}/events/batch` and `GET /v1/traces/{external_id}` create a shared trace from its `beacon.trace.v1` summary, upsert its trace events, and read it back (with the id of the last event held) for `beacon share`, with the access token (or a `bcn_api_` API key) as a Bearer credential. They require `traces:write`.
- `POST /api/cli/auth/revoke` accepts the access token as a Bearer credential and revokes it.
`beacon login` requests `profile:read`, `device:enroll`, `mcp:token:create` and `traces:write`. A later `beacon endpoint connect` can use `device:enroll` to mint a device-specific ingest key without treating the account token as an ingest credential, and `beacon mcp token create` uses `mcp:token:create` to mint a personal MCP token. beacon.sh approves the sign-in only when the permissions its page showed match the ones the CLI registered, so a crafted link cannot hide one. `beacon share` uses `traces:write` to upload a session you choose to share. A session from an older `beacon login` lacks `mcp:token:create` or `traces:write`; run `beacon login` again to create MCP tokens or share traces from the CLI.