Skip to content

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

Add cloud agent telemetry upload support

shukieshahaff045575908
diff --git a/cli/beacon-hooks/cmd/endpoint_events.go b/cli/beacon-hooks/cmd/endpoint_events.go
index 9cac2c67..20d7969c 100644
--- a/cli/beacon-hooks/cmd/endpoint_events.go
+++ b/cli/beacon-hooks/cmd/endpoint_events.go
@@ -1,12 +1,15 @@
package cmd
import (
+ "context"
"crypto/sha256"
"encoding/hex"
"fmt"
"path/filepath"
"strings"
+ "time"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/cloudshuttle"
"github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/logging"
)
@@ -39,6 +42,15 @@ func emitHookEvent(logger *logging.Logger, action, category, severity, message s
if err := logger.EndpointEvent(action, category, severity, message, fields); err != nil {
logger.Error("Failed to write endpoint event", "error", err.Error(), "action", action)
}
+ uploadCloudTelemetry(logger, false)
+}
+
+func uploadCloudTelemetry(logger *logging.Logger, force bool) {
+ ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+ defer cancel()
+ if err := cloudshuttle.MaybeUpload(ctx, force); err != nil {
+ logger.Warn("Cloud telemetry upload failed", "error", err.Error(), "force", force)
+ }
}
func sessionFields(sessionID string, input map[string]interface{}) map[string]interface{} {
diff --git a/cli/beacon-hooks/cmd/session_end.go b/cli/beacon-hooks/cmd/session_end.go
index c17a5e03..53f737ae 100644
--- a/cli/beacon-hooks/cmd/session_end.go
+++ b/cli/beacon-hooks/cmd/session_end.go
@@ -36,6 +36,7 @@ func runSessionEnd(cmd *cobra.Command, args []string) {
logger := logging.NewSessionLogger("session-end", platformFlag, sessionID)
logger.Info("Session ended", "session_id", sessionID, "platform", platformFlag)
emitHookEvent(logger, "session.ended", "session", "info", "Agent session ended", input, sessionFields(sessionID, input))
+ uploadCloudTelemetry(logger, true)
logFile := config.GetSessionLogFile(platformFlag, sessionID)
if err := os.Remove(logFile); err != nil && !os.IsNotExist(err) {
@@ -44,6 +45,7 @@ func runSessionEnd(cmd *cobra.Command, args []string) {
} else if isDevinLikePlatform(platformFlag) {
platformLogger.Info("Session ended", "platform", platformFlag)
emitHookEvent(platformLogger, "session.ended", "session", "info", "Agent session ended", input, sessionFields("", input))
+ uploadCloudTelemetry(platformLogger, true)
}
cleaned := state.CleanupStaleForPlatform(platformFlag)
diff --git a/cli/beacon-hooks/cmd/stop.go b/cli/beacon-hooks/cmd/stop.go
index 0add11bc..0e555e08 100644
--- a/cli/beacon-hooks/cmd/stop.go
+++ b/cli/beacon-hooks/cmd/stop.go
@@ -50,9 +50,11 @@ func runStop(cmd *cobra.Command, args []string) {
if isDevinLikePlatform(platformFlag) {
logger.Info("stop completed")
emitHookEvent(logger, "tool.completed", "tool", "info", "Agent response completed", input, sessionFields("", input))
+ uploadCloudTelemetry(logger, true)
outputJSON(emptyResponse)
return
}
+ uploadCloudTelemetry(logger, true)
outputJSONAndExit(emptyResponse)
return
}
@@ -74,6 +76,7 @@ func runStop(cmd *cobra.Command, args []string) {
elapsed := time.Since(start)
logger.Info("stop completed", "duration_ms", elapsed.Milliseconds())
emitHookEvent(logger, "tool.completed", "tool", "info", "Agent response completed", input, sessionFields(sessionID, input))
+ uploadCloudTelemetry(logger, true)
outputJSONAndExit(emptyResponse)
}
diff --git a/cli/beacon-hooks/internal/cloudshuttle/shuttle.go b/cli/beacon-hooks/internal/cloudshuttle/shuttle.go
new file mode 100644
index 00000000..f05e812f
--- /dev/null
+++ b/cli/beacon-hooks/internal/cloudshuttle/shuttle.go
@@ -0,0 +1,429 @@
+package cloudshuttle
+
+import (
+ "bytes"
+ "context"
+ "crypto"
+ "crypto/rand"
+ "crypto/rsa"
+ "crypto/sha256"
+ "crypto/x509"
+ "encoding/base64"
+ "encoding/json"
+ "encoding/pem"
+ "errors"
+ "fmt"
+ "io"
+ "net/http"
+ "net/url"
+ "os"
+ "path"
+ "path/filepath"
+ "strconv"
+ "strings"
+ "syscall"
+ "time"
+)
+
+const (
+ defaultInterval = 60 * time.Second
+ defaultLogPath = "/tmp/beacon/runtime.jsonl"
+ defaultStatePath = "/tmp/beacon/shuttle-state.json"
+ defaultTokenURI = "https://oauth2.googleapis.com/token"
+ defaultGCSEndpoint = "https://storage.googleapis.com"
+ contentTypeJSONL = "application/x-ndjson"
+)
+
+var httpClient = http.DefaultClient
+
+type Config struct {
+ LogPath string
+ StatePath string
+ Bucket string
+ Prefix string
+ CredentialsB64 string
+ Interval time.Duration
+ Provider string
+ RunID string
+ UserID string
+ Repository string
+ GCSEndpoint string
+}
+
+type serviceAccount struct {
+ ClientEmail string `json:"client_email"`
+ PrivateKey string `json:"private_key"`
+ TokenURI string `json:"token_uri"`
+}
+
+type state struct {
+ LastUpload string `json:"last_upload,omitempty"`
+ LastSize int64 `json:"last_size,omitempty"`
+}
+
+type tokenResponse struct {
+ AccessToken string `json:"access_token"`
+ TokenType string `json:"token_type"`
+ ExpiresIn int `json:"expires_in"`
+}
+
+func ConfigFromEnv() Config {
+ interval := defaultInterval
+ if raw := strings.TrimSpace(os.Getenv("BEACON_CLOUD_UPLOAD_INTERVAL")); raw != "" {
+ if raw == "0" {
+ interval = 0
+ } else if parsed, err := time.ParseDuration(raw); err == nil {
+ interval = parsed
+ }
+ }
+ return Config{
+ LogPath: firstEnvDefault(defaultLogPath, "BEACON_CLOUD_LOG_PATH", "BEACON_ENDPOINT_LOG", "BEACON_LOG_PATH", "BEACON_RUNTIME_LOG"),
+ StatePath: firstEnvDefault(defaultStatePath, "BEACON_CLOUD_SHUTTLE_STATE"),
+ Bucket: strings.TrimSpace(os.Getenv("BEACON_CLOUD_GCS_BUCKET")),
+ Prefix: strings.Trim(strings.TrimSpace(os.Getenv("BEACON_CLOUD_GCS_PREFIX")), "/"),
+ CredentialsB64: strings.TrimSpace(os.Getenv("BEACON_CLOUD_GCS_CREDENTIALS_B64")),
+ Interval: interval,
+ Provider: firstEnvDefault("claude_code_web", "BEACON_RUN_PROVIDER"),
+ RunID: firstEnvDefault(fmt.Sprintf("manual-%d", time.Now().UTC().UnixNano()), "BEACON_RUN_ID", "CLAUDE_CODE_REMOTE_SESSION_ID"),
+ UserID: firstEnvDefault("unknown", "BEACON_CLOUD_USER_ID_HASH", "BEACON_CLOUD_USER_ID"),
+ Repository: firstEnv("BEACON_RUN_REPOSITORY"),
+ GCSEndpoint: firstEnvDefault(defaultGCSEndpoint, "BEACON_CLOUD_GCS_ENDPOINT"),
+ }
+}
+
+func MaybeUpload(ctx context.Context, force bool) error {
+ return Upload(ctx, ConfigFromEnv(), force)
+}
+
+func Upload(ctx context.Context, cfg Config, force bool) error {
+ if strings.TrimSpace(cfg.Bucket) == "" || strings.TrimSpace(cfg.CredentialsB64) == "" {
+ return nil
+ }
+ if cfg.LogPath == "" {
+ cfg.LogPath = defaultLogPath
+ }
+ if cfg.StatePath == "" {
+ cfg.StatePath = defaultStatePath
+ }
+ if cfg.GCSEndpoint == "" {
+ cfg.GCSEndpoint = defaultGCSEndpoint
+ }
+ info, err := os.Stat(cfg.LogPath)
+ if err != nil {
+ if os.IsNotExist(err) {
+ return nil
+ }
+ return err
+ }
+ if info.Size() == 0 {
+ return nil
+ }
+ if !force && !uploadDue(cfg, info.Size(), time.Now().UTC()) {
+ return nil
+ }
+ snapshot, cleanup, err := snapshotLog(cfg.LogPath)
+ if err != nil {
+ return err
+ }
+ defer cleanup()
+ token, err := accessToken(ctx, cfg.CredentialsB64)
+ if err != nil {
+ return err
+ }
+ objectName := ObjectName(cfg)
+ if err := uploadObject(ctx, cfg.GCSEndpoint, cfg.Bucket, objectName, snapshot, token); err != nil {
+ return err
+ }
+ return writeState(cfg.StatePath, state{
+ LastUpload: time.Now().UTC().Format(time.RFC3339),
+ LastSize: info.Size(),
+ })
+}
+
+func ObjectName(cfg Config) string {
+ parts := cleanKeyParts(cfg.Prefix)
+ parts = append(parts, "provider="+cleanKeyPart(defaultString(cfg.Provider, "unknown")))
+ if cfg.UserID != "" {
+ parts = append(parts, "user_id="+cleanKeyPart(cfg.UserID))
+ }
+ if cfg.Repository != "" {
+ parts = append(parts, cleanKeyParts("repo="+cfg.Repository)...)
+ }
+ parts = append(parts, "run_id="+cleanKeyPart(defaultString(cfg.RunID, "unknown")))
+ parts = append(parts, "runtime.jsonl")
+ return path.Join(parts...)
+}
+
+func uploadDue(cfg Config, currentSize int64, now time.Time) bool {
+ if cfg.Interval <= 0 {
+ return false
+ }
+ st, err := readState(cfg.StatePath)
+ if err != nil {
+ return true
+ }
+ if currentSize != st.LastSize {
+ // Still respect interval to avoid uploading on every hook during active runs.
+ }
+ if st.LastUpload == "" {
+ return true
+ }
+ last, err := time.Parse(time.RFC3339, st.LastUpload)
+ if err != nil {
+ return true
+ }
+ return now.Sub(last) >= cfg.Interval
+}
+
+func snapshotLog(logPath string) (string, func(), error) {
+ lock, err := os.OpenFile(logPath+".lock", os.O_CREATE|os.O_RDWR, 0644)
+ if err != nil {
+ return "", func() {}, err
+ }
+ if err := syscall.Flock(int(lock.Fd()), syscall.LOCK_SH); err != nil {
+ _ = lock.Close()
+ return "", func() {}, err
+ }
+ defer syscall.Flock(int(lock.Fd()), syscall.LOCK_UN)
+ defer lock.Close()
+
+ source, err := os.Open(logPath)
+ if err != nil {
+ return "", func() {}, err
+ }
+ defer source.Close()
+ if err := os.MkdirAll(filepath.Dir(logPath), 0755); err != nil {
+ return "", func() {}, err
+ }
+ temp, err := os.CreateTemp(filepath.Dir(logPath), "beacon-cloud-*.jsonl")
+ if err != nil {
+ return "", func() {}, err
+ }
+ tempPath := temp.Name()
+ cleanup := func() { _ = os.Remove(tempPath) }
+ if _, err := io.Copy(temp, source); err != nil {
+ _ = temp.Close()
+ cleanup()
+ return "", func() {}, err
+ }
+ if err := temp.Close(); err != nil {
+ cleanup()
+ return "", func() {}, err
+ }
+ return tempPath, cleanup, nil
+}
+
+func accessToken(ctx context.Context, credentialsB64 string) (string, error) {
+ decoded, err := base64.StdEncoding.DecodeString(credentialsB64)
+ if err != nil {
+ return "", fmt.Errorf("decode GCS credentials: %w", err)
+ }
+ var account serviceAccount
+ if err := json.Unmarshal(decoded, &account); err != nil {
+ return "", fmt.Errorf("parse GCS credentials: %w", err)
+ }
+ if account.ClientEmail == "" || account.PrivateKey == "" {
+ return "", errors.New("GCS credentials missing client_email or private_key")
+ }
+ if account.TokenURI == "" {
+ account.TokenURI = defaultTokenURI
+ }
+ assertion, err := signedJWT(account)
+ if err != nil {
+ return "", err
+ }
+ form := url.Values{}
+ form.Set("grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer")
+ form.Set("assertion", assertion)
+ req, err := http.NewRequestWithContext(ctx, http.MethodPost, account.TokenURI, strings.NewReader(form.Encode()))
+ if err != nil {
+ return "", err
+ }
+ req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+ resp, err := httpClient.Do(req)
+ if err != nil {
+ return "", err
+ }
+ defer resp.Body.Close()
+ body, _ := io.ReadAll(io.LimitReader(resp.Body, 64*1024))
+ if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+ return "", fmt.Errorf("GCS token exchange failed: %s: %s", resp.Status, strings.TrimSpace(string(body)))
+ }
+ var token tokenResponse
+ if err := json.Unmarshal(body, &token); err != nil {
+ return "", fmt.Errorf("parse GCS token response: %w", err)
+ }
+ if token.AccessToken == "" {
+ return "", errors.New("GCS token response missing access_token")
+ }
+ return token.AccessToken, nil
+}
+
+func signedJWT(account serviceAccount) (string, error) {
+ now := time.Now().Unix()
+ header := map[string]string{"alg": "RS256", "typ": "JWT"}
+ claims := map[string]interface{}{
+ "iss": account.ClientEmail,
+ "scope": "https://www.googleapis.com/auth/devstorage.read_write",
+ "aud": account.TokenURI,
+ "iat": now,
+ "exp": now + 3600,
+ }
+ encodedHeader, err := encodeJSONSegment(header)
+ if err != nil {
+ return "", err
+ }
+ encodedClaims, err := encodeJSONSegment(claims)
+ if err != nil {
+ return "", err
+ }
+ signingInput := encodedHeader + "." + encodedClaims
+ privateKey, err := parseRSAPrivateKey(account.PrivateKey)
+ if err != nil {
+ return "", err
+ }
+ sum := sha256.Sum256([]byte(signingInput))
+ signature, err := rsa.SignPKCS1v15(rand.Reader, privateKey, crypto.SHA256, sum[:])
+ if err != nil {
+ return "", err
+ }
+ return signingInput + "." + base64.RawURLEncoding.EncodeToString(signature), nil
+}
+
+func encodeJSONSegment(value interface{}) (string, error) {
+ data, err := json.Marshal(value)
+ if err != nil {
+ return "", err
+ }
+ return base64.RawURLEncoding.EncodeToString(data), nil
+}
+
+func parseRSAPrivateKey(raw string) (*rsa.PrivateKey, error) {
+ block, _ := pem.Decode([]byte(raw))
+ if block == nil {
+ return nil, errors.New("GCS private key is not PEM encoded")
+ }
+ if key, err := x509.ParsePKCS8PrivateKey(block.Bytes); err == nil {
+ if rsaKey, ok := key.(*rsa.PrivateKey); ok {
+ return rsaKey, nil
+ }
+ return nil, errors.New("GCS private key is not RSA")
+ }
+ if key, err := x509.ParsePKCS1PrivateKey(block.Bytes); err == nil {
+ return key, nil
+ }
+ return nil, errors.New("parse GCS private key")
+}
+
+func uploadObject(ctx context.Context, endpoint, bucket, objectName, filePath, token string) error {
+ file, err := os.Open(filePath)
+ if err != nil {
+ return err
+ }
+ defer file.Close()
+ uploadURL := strings.TrimRight(endpoint, "/") + "/" + escapePath(bucket) + "/" + escapeObjectName(objectName)
+ req, err := http.NewRequestWithContext(ctx, http.MethodPut, uploadURL, file)
+ if err != nil {
+ return err
+ }
+ if info, err := file.Stat(); err == nil {
+ req.ContentLength = info.Size()
+ }
+ req.Header.Set("Authorization", "Bearer "+token)
+ req.Header.Set("Content-Type", contentTypeJSONL)
+ resp, err := httpClient.Do(req)
+ if err != nil {
+ return err
+ }
+ defer resp.Body.Close()
+ body, _ := io.ReadAll(io.LimitReader(resp.Body, 64*1024))
+ if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+ return fmt.Errorf("GCS upload failed: %s: %s", resp.Status, strings.TrimSpace(string(body)))
+ }
+ return nil
+}
+
+func readState(path string) (state, error) {
+ var st state
+ data, err := os.ReadFile(path)
+ if err != nil {
+ return st, err
+ }
+ err = json.Unmarshal(data, &st)
+ return st, err
+}
+
+func writeState(path string, st state) error {
+ if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+ return err
+ }
+ data, err := json.Marshal(st)
+ if err != nil {
+ return err
+ }
+ return os.WriteFile(path, data, 0644)
+}
+
+func cleanKeyParts(value string) []string {
+ var parts []string
+ for _, part := range strings.Split(strings.Trim(value, "/"), "/") {
+ if cleaned := cleanKeyPart(part); cleaned != "" {
+ parts = append(parts, cleaned)
+ }
+ }
+ return parts
+}
+
+func cleanKeyPart(value string) string {
+ cleaned := strings.TrimSpace(value)
+ cleaned = strings.ReplaceAll(cleaned, "\\", "-")
+ cleaned = strings.Trim(cleaned, "/")
+ if cleaned == "." || cleaned == ".." {
+ return ""
+ }
+ return cleaned
+}
+
+func escapeObjectName(objectName string) string {
+ parts := strings.Split(objectName, "/")
+ for i, part := range parts {
+ parts[i] = escapePath(part)
+ }
+ return strings.Join(parts, "/")
+}
+
+func escapePath(value string) string {
+ return (&url.URL{Path: value}).EscapedPath()
+}
+
+func defaultString(value, fallback string) string {
+ if strings.TrimSpace(value) == "" {
+ return fallback
+ }
+ return value
+}
+
+func firstEnv(keys ...string) string {
+ for _, key := range keys {
+ if value := strings.TrimSpace(os.Getenv(key)); value != "" {
+ return value
+ }
+ }
+ return ""
+}
+
+func firstEnvDefault(defaultValue string, keys ...string) string {
+ if value := firstEnv(keys...); value != "" {
+ return value
+ }
+ return defaultValue
+}
+
+func EncodeCredentialsForEnv(data []byte) string {
+ return base64.StdEncoding.EncodeToString(bytes.TrimSpace(data))
+}
+
+func ParseBoolEnv(key string) bool {
+ value, _ := strconv.ParseBool(strings.TrimSpace(os.Getenv(key)))
+ return value
+}
diff --git a/cli/beacon-hooks/internal/cloudshuttle/shuttle_test.go b/cli/beacon-hooks/internal/cloudshuttle/shuttle_test.go
new file mode 100644
index 00000000..41daf73b
--- /dev/null
+++ b/cli/beacon-hooks/internal/cloudshuttle/shuttle_test.go
@@ -0,0 +1,137 @@
+package cloudshuttle
+
+import (
+ "context"
+ "crypto/rand"
+ "crypto/rsa"
+ "crypto/x509"
+ "encoding/base64"
+ "encoding/json"
+ "encoding/pem"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+)
+
+func TestObjectNamePartitionsByProviderUserRepoAndRun(t *testing.T) {
+ got := ObjectName(Config{
+ Prefix: "agent-traces/customer=test",
+ Provider: "claude_code_web",
+ UserID: "user-1",
+ Repository: "asymptote-labs/agent-beacon",
+ RunID: "cse_123",
+ })
+ want := "agent-traces/customer=test/provider=claude_code_web/user_id=user-1/repo=asymptote-labs/agent-beacon/run_id=cse_123/runtime.jsonl"
+ if got != want {
+ t.Fatalf("ObjectName = %q, want %q", got, want)
+ }
+}
+
+func TestUploadNoopsWithoutCredentials(t *testing.T) {
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ if err := os.WriteFile(logPath, []byte("{}\n"), 0644); err != nil {
+ t.Fatalf("write log: %v", err)
+ }
+ if err := Upload(context.Background(), Config{LogPath: logPath, Bucket: "bucket"}, true); err != nil {
+ t.Fatalf("Upload returned error: %v", err)
+ }
+}
+
+func TestUploadSendsJSONLToGCS(t *testing.T) {
+ key := mustRSAKey(t)
+ var uploadedPath, uploadedAuth, uploadedType, uploadedBody string
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch r.URL.Path {
+ case "/token":
+ if err := r.ParseForm(); err != nil {
+ t.Fatalf("parse form: %v", err)
+ }
+ if r.Form.Get("grant_type") != "urn:ietf:params:oauth:grant-type:jwt-bearer" || r.Form.Get("assertion") == "" {
+ t.Fatalf("unexpected token request: %s", r.Form.Encode())
+ }
+ _ = json.NewEncoder(w).Encode(map[string]interface{}{"access_token": "test-token", "token_type": "Bearer", "expires_in": 3600})
+ default:
+ uploadedPath = r.URL.EscapedPath()
+ uploadedAuth = r.Header.Get("Authorization")
+ uploadedType = r.Header.Get("Content-Type")
+ data, _ := io.ReadAll(r.Body)
+ uploadedBody = string(data)
+ w.WriteHeader(http.StatusOK)
+ }
+ }))
+ defer server.Close()
+
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ if err := os.WriteFile(logPath, []byte("{\"event\":\"ok\"}\n"), 0644); err != nil {
+ t.Fatalf("write log: %v", err)
+ }
+ creds := serviceAccount{
+ ClientEmail: "[email protected]",
+ PrivateKey: pemKey(t, key),
+ TokenURI: server.URL + "/token",
+ }
+ credsJSON, err := json.Marshal(creds)
+ if err != nil {
+ t.Fatalf("marshal creds: %v", err)
+ }
+ cfg := Config{
+ LogPath: logPath,
+ StatePath: filepath.Join(t.TempDir(), "state.json"),
+ Bucket: "bucket",
+ Prefix: "prefix",
+ CredentialsB64: base64.StdEncoding.EncodeToString(credsJSON),
+ Provider: "claude_code_web",
+ UserID: "user",
+ RunID: "run",
+ GCSEndpoint: server.URL,
+ }
+ if err := Upload(context.Background(), cfg, true); err != nil {
+ t.Fatalf("Upload returned error: %v", err)
+ }
+ if uploadedAuth != "Bearer test-token" {
+ t.Fatalf("Authorization = %q, want bearer token", uploadedAuth)
+ }
+ if uploadedType != contentTypeJSONL {
+ t.Fatalf("Content-Type = %q, want %q", uploadedType, contentTypeJSONL)
+ }
+ if !strings.Contains(uploadedPath, "/bucket/prefix/provider=claude_code_web/user_id=user/run_id=run/runtime.jsonl") {
+ t.Fatalf("upload path = %q", uploadedPath)
+ }
+ if uploadedBody != "{\"event\":\"ok\"}\n" {
+ t.Fatalf("uploaded body = %q", uploadedBody)
+ }
+}
+
+func TestUploadRespectsInterval(t *testing.T) {
+ dir := t.TempDir()
+ statePath := filepath.Join(dir, "state.json")
+ if err := writeState(statePath, state{LastUpload: time.Now().UTC().Format(time.RFC3339), LastSize: 10}); err != nil {
+ t.Fatalf("write state: %v", err)
+ }
+ if uploadDue(Config{StatePath: statePath, Interval: time.Hour}, 11, time.Now().UTC()) {
+ t.Fatal("uploadDue = true, want false inside interval")
+ }
+}
+
+func mustRSAKey(t *testing.T) *rsa.PrivateKey {
+ t.Helper()
+ key, err := rsa.GenerateKey(rand.Reader, 2048)
+ if err != nil {
+ t.Fatalf("generate key: %v", err)
+ }
+ return key
+}
+
+func pemKey(t *testing.T, key *rsa.PrivateKey) string {
+ t.Helper()
+ data, err := x509.MarshalPKCS8PrivateKey(key)
+ if err != nil {
+ t.Fatalf("marshal key: %v", err)
+ }
+ return string(pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: data}))
+}
diff --git a/cli/beacon-hooks/internal/logging/endpoint_event_test.go b/cli/beacon-hooks/internal/logging/endpoint_event_test.go
index 861caa29..a5dc3f8d 100644
--- a/cli/beacon-hooks/internal/logging/endpoint_event_test.go
+++ b/cli/beacon-hooks/internal/logging/endpoint_event_test.go
@@ -1,6 +1,7 @@
package logging
import (
+ "encoding/json"
"os"
"path/filepath"
"strings"
@@ -40,6 +41,44 @@ func TestEndpointEventStillWritesStructuredTelemetry(t *testing.T) {
}
}
+func TestEndpointEventAddsCloudRunMetadataFromEnvironment(t *testing.T) {
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ t.Setenv("BEACON_ORIGIN", "cloud")
+ t.Setenv("BEACON_RUN_PROVIDER", "claude_code_web")
+ t.Setenv("CLAUDE_CODE_REMOTE_SESSION_ID", "cse_123")
+ t.Setenv("BEACON_RUN_REPOSITORY", "asymptote-labs/agent-beacon")
+ t.Setenv("BEACON_RUN_BRANCH", "main")
+ t.Setenv("BEACON_RUN_ACTOR", "[email protected]")
+ t.Setenv("BEACON_RUN_EPHEMERAL", "true")
+ t.Setenv("BEACON_CLOUD_USER_ID_HASH", "user-hash")
+
+ logger := NewLoggerForPlatform("session-start", "claude")
+ if err := logger.EndpointEvent("session.started", "session", "info", "Session started", nil); err != nil {
+ t.Fatalf("EndpointEvent returned error: %v", err)
+ }
+
+ data, err := os.ReadFile(logPath)
+ if err != nil {
+ t.Fatalf("read endpoint log: %v", err)
+ }
+ var event map[string]interface{}
+ if err := json.Unmarshal([]byte(strings.TrimSpace(string(data))), &event); err != nil {
+ t.Fatalf("unmarshal event: %v", err)
+ }
+ if got := event["origin"]; got != "cloud" {
+ t.Fatalf("origin = %q, want cloud", got)
+ }
+ run := event["run"].(map[string]interface{})
+ if run["provider"] != "claude_code_web" || run["run_id"] != "cse_123" || run["repository"] != "asymptote-labs/agent-beacon" || run["branch"] != "main" || run["actor"] != "[email protected]" || run["ephemeral"] != true {
+ t.Fatalf("run metadata = %#v", run)
+ }
+ user := event["user"].(map[string]interface{})
+ if user["uid"] != "user-hash" {
+ t.Fatalf("user uid = %q, want user-hash", user["uid"])
+ }
+}
+
func TestEndpointEventRotatesRuntimeLog(t *testing.T) {
logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
if err := os.WriteFile(logPath, []byte("old log contents"), 0644); err != nil {
diff --git a/cli/beacon-hooks/internal/logging/logging.go b/cli/beacon-hooks/internal/logging/logging.go
index 869b2e57..d9a37551 100644
--- a/cli/beacon-hooks/internal/logging/logging.go
+++ b/cli/beacon-hooks/internal/logging/logging.go
@@ -118,6 +118,12 @@ func (l *Logger) EndpointEvent(action, category, severity, message string, field
func (l *Logger) baseEndpointEvent(action, category, severity, message string) map[string]interface{} {
hostname, _ := os.Hostname()
+ user := map[string]interface{}{
+ "name": os.Getenv("USER"),
+ }
+ if uid := firstEnv("BEACON_CLOUD_USER_ID", "BEACON_CLOUD_USER_ID_HASH"); uid != "" {
+ user["uid"] = uid
+ }
event := map[string]interface{}{
"timestamp": time.Now().UTC().Format(time.RFC3339),
"vendor": "beacon",
@@ -133,20 +139,79 @@ func (l *Logger) baseEndpointEvent(action, category, severity, message string) m
"hostname": hostname,
"os": runtime.GOOS,
},
- "user": map[string]interface{}{
- "name": os.Getenv("USER"),
- },
+ "user": user,
"harness": map[string]interface{}{
"name": l.platform,
},
"message": asymptoteobserve.CleanString(message, asymptoteobserve.DefaultStringLimit, true),
}
+ if origin := firstEnv("BEACON_ORIGIN"); origin != "" {
+ event["origin"] = origin
+ }
+ if run := cloudRunFields(); len(run) > 0 {
+ event["run"] = run
+ }
if l.sessionID != "" {
event["session"] = map[string]interface{}{"id": l.sessionID}
}
return event
}
+func cloudRunFields() map[string]interface{} {
+ run := map[string]interface{}{}
+ if provider := firstEnv("BEACON_RUN_PROVIDER"); provider != "" {
+ run["provider"] = provider
+ }
+ if runID := firstEnv("BEACON_RUN_ID", "CLAUDE_CODE_REMOTE_SESSION_ID"); runID != "" {
+ run["run_id"] = runID
+ }
+ if attempt := firstEnv("BEACON_RUN_ATTEMPT"); attempt != "" {
+ run["run_attempt"] = attempt
+ }
+ if workflow := firstEnv("BEACON_RUN_WORKFLOW"); workflow != "" {
+ run["workflow"] = workflow
+ }
+ if job := firstEnv("BEACON_RUN_JOB"); job != "" {
+ run["job"] = job
+ }
+ if eventName := firstEnv("BEACON_RUN_EVENT_NAME"); eventName != "" {
+ run["event_name"] = eventName
+ }
+ if commit := firstEnv("BEACON_RUN_COMMIT"); commit != "" {
+ run["commit"] = commit
+ }
+ if repository := firstEnv("BEACON_RUN_REPOSITORY"); repository != "" {
+ run["repository"] = repository
+ }
+ if branch := firstEnv("BEACON_RUN_BRANCH"); branch != "" {
+ run["branch"] = branch
+ }
+ if pr := firstEnv("BEACON_RUN_PR"); pr != "" {
+ run["pr"] = pr
+ }
+ if prNumber := firstEnv("BEACON_RUN_PR_NUMBER"); prNumber != "" {
+ run["pr_number"] = prNumber
+ }
+ if actor := firstEnv("BEACON_RUN_ACTOR"); actor != "" {
+ run["actor"] = actor
+ }
+ if ephemeral := firstEnv("BEACON_RUN_EPHEMERAL"); ephemeral != "" {
+ if value, err := strconv.ParseBool(ephemeral); err == nil {
+ run["ephemeral"] = value
+ }
+ }
+ return run
+}
+
+func firstEnv(keys ...string) string {
+ for _, key := range keys {
+ if value := strings.TrimSpace(os.Getenv(key)); value != "" {
+ return value
+ }
+ }
+ return ""
+}
+
func writeEndpointJSON(path string, event map[string]interface{}) error {
if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
return err
diff --git a/cli/beacon/.goreleaser.yaml b/cli/beacon/.goreleaser.yaml
index ef68b854..fd649966 100644
--- a/cli/beacon/.goreleaser.yaml
+++ b/cli/beacon/.goreleaser.yaml
@@ -42,11 +42,30 @@ builds:
# hooks.bin instead of serving a stale copy from cache.
- cmd: bash -c 'cd ../beacon-hooks && GOOS={{ .Os }} GOARCH={{ .Arch }} go build -ldflags "-s -w -X github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/version.Version={{ .Version }}" -o ../beacon/internal/embedded/hooks.bin .'
output: true
+ - id: beacon-hooks
+ main: ../beacon-hooks
+ binary: beacon-hooks
+ env:
+ - CGO_ENABLED=0
+ flags:
+ - -a
+ ldflags:
+ - -s -w
+ - -X github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/version.Version={{.Version}}
+ goos:
+ - darwin
+ - linux
+ goarch:
+ - amd64
+ - arm64
archives:
- formats:
- tar.gz
name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
+ builds:
+ - beacon
+ - beacon-hooks
files:
- README*
- src: release-collectors/{{ .Os }}_{{ .Arch }}/beacon-otelcol
@@ -92,6 +111,7 @@ brews:
commit_msg_template: "Homebrew formula update for {{ .ProjectName }} version {{ .Tag }}"
install: |
bin.install "beacon"
+ bin.install "beacon-hooks"
bin.install "beacon-otelcol"
caveats: |
To configure local endpoint telemetry, run:
diff --git a/cli/beacon/cmd/cloud.go b/cli/beacon/cmd/cloud.go
new file mode 100644
index 00000000..51c71bb6
--- /dev/null
+++ b/cli/beacon/cmd/cloud.go
@@ -0,0 +1,338 @@
+package cmd
+
+import (
+ "encoding/base64"
+ "encoding/json"
+ "fmt"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "strings"
+ "time"
+
+ "github.com/spf13/cobra"
+)
+
+var cloudOpts struct {
+ binaryPath string
+ logPath string
+ version string
+ project string
+ bucket string
+ location string
+ prefix string
+ serviceAccount string
+ printOnly bool
+ apply bool
+ printEnv bool
+}
+
+var cloudCmd = &cobra.Command{
+ Use: "cloud",
+ Short: "Configure Beacon telemetry for provider-managed cloud agents",
+}
+
+var cloudClaudeWebCmd = &cobra.Command{
+ Use: "claude-web",
+ Short: "Generate Claude Code on the web telemetry setup",
+}
+
+var cloudClaudeWebPrintHooksCmd = &cobra.Command{
+ Use: "print-hooks",
+ Short: "Print project-level Claude hook settings for a cloud sandbox",
+ SilenceUsage: true,
+ RunE: func(cmd *cobra.Command, args []string) error {
+ if strings.TrimSpace(cloudOpts.binaryPath) == "" {
+ return fmt.Errorf("--binary-path is required")
+ }
+ if strings.TrimSpace(cloudOpts.logPath) == "" {
+ cloudOpts.logPath = "/tmp/beacon/runtime.jsonl"
+ }
+ fmt.Print(renderClaudeWebHooks(cloudOpts.binaryPath, cloudOpts.logPath))
+ return nil
+ },
+}
+
+var cloudClaudeWebPrintSetupCmd = &cobra.Command{
+ Use: "print-setup",
+ Short: "Print a Claude Code web environment setup script",
+ SilenceUsage: true,
+ RunE: func(cmd *cobra.Command, args []string) error {
+ if strings.TrimSpace(cloudOpts.version) == "" {
+ return fmt.Errorf("--version is required")
+ }
+ fmt.Print(renderClaudeWebSetup(cloudOpts.version))
+ return nil
+ },
+}
+
+var cloudGCSCmd = &cobra.Command{
+ Use: "gcs",
+ Short: "Configure GCS forwarding for cloud agent telemetry",
+}
+
+var cloudGCSSetupCmd = &cobra.Command{
+ Use: "setup",
+ Short: "Create or print self-serve GCS setup for cloud agent telemetry",
+ SilenceUsage: true,
+ RunE: runCloudGCSSetup,
+}
+
+func init() {
+ rootCmd.AddCommand(cloudCmd)
+ cloudCmd.AddCommand(cloudClaudeWebCmd)
+ cloudCmd.AddCommand(cloudGCSCmd)
+ cloudClaudeWebCmd.AddCommand(cloudClaudeWebPrintHooksCmd)
+ cloudClaudeWebCmd.AddCommand(cloudClaudeWebPrintSetupCmd)
+ cloudGCSCmd.AddCommand(cloudGCSSetupCmd)
+
+ cloudClaudeWebPrintHooksCmd.Flags().StringVar(&cloudOpts.binaryPath, "binary-path", "", "Path to beacon-hooks inside the cloud sandbox")
+ cloudClaudeWebPrintHooksCmd.Flags().StringVar(&cloudOpts.logPath, "log-path", "/tmp/beacon/runtime.jsonl", "Cloud sandbox runtime JSONL path")
+ cloudClaudeWebPrintSetupCmd.Flags().StringVar(&cloudOpts.version, "version", "", "Beacon release tag to download, such as v0.0.50")
+
+ cloudGCSSetupCmd.Flags().StringVar(&cloudOpts.project, "project", "", "Google Cloud project ID")
+ cloudGCSSetupCmd.Flags().StringVar(&cloudOpts.bucket, "bucket", "", "GCS bucket for cloud agent telemetry")
+ cloudGCSSetupCmd.Flags().StringVar(&cloudOpts.location, "location", "us-central1", "GCS bucket location when creating a bucket")
+ cloudGCSSetupCmd.Flags().StringVar(&cloudOpts.prefix, "prefix", "agent-traces", "GCS object prefix for cloud telemetry")
+ cloudGCSSetupCmd.Flags().StringVar(&cloudOpts.serviceAccount, "service-account", "beacon-cloud-trace-uploader", "Uploader service account ID or email")
+ cloudGCSSetupCmd.Flags().BoolVar(&cloudOpts.printOnly, "print", false, "Print the gcloud commands without running them")
+ cloudGCSSetupCmd.Flags().BoolVar(&cloudOpts.apply, "apply", false, "Run the gcloud setup commands")
+ cloudGCSSetupCmd.Flags().BoolVar(&cloudOpts.printEnv, "print-env", false, "Print Claude web environment variables after setup")
+}
+
+func renderClaudeWebHooks(binaryPath, logPath string) string {
+ prefix := fmt.Sprintf("BEACON_ENDPOINT_MODE=1 BEACON_ENDPOINT_LOG=%s %s --platform claude", shellQuote(logPath), shellQuote(binaryPath))
+ hooks := map[string][]map[string]interface{}{
+ "SessionStart": {
+ {"hooks": []map[string]interface{}{{"type": "command", "command": prefix + " session-start"}}},
+ },
+ "UserPromptSubmit": {
+ {"hooks": []map[string]interface{}{{"type": "command", "command": prefix + " prompt-submit", "timeout": 30}}},
+ },
+ "PreToolUse": {
+ {"matcher": "Bash|Edit|Write|MultiEdit|Read|Glob|Grep|WebFetch|WebSearch|Agent|mcp__.*", "hooks": []map[string]interface{}{{"type": "command", "command": prefix + " pre-tool"}}},
+ },
+ "PostToolUse": {
+ {"matcher": "*", "hooks": []map[string]interface{}{{"type": "command", "command": prefix + " post-tool"}}},
+ },
+ "PostToolUseFailure": {
+ {"matcher": "*", "hooks": []map[string]interface{}{{"type": "command", "command": prefix + " post-tool"}}},
+ },
+ "Stop": {
+ {"hooks": []map[string]interface{}{{"type": "command", "command": prefix + " stop", "timeout": 45}}},
+ },
+ "SubagentStart": {
+ {"hooks": []map[string]interface{}{{"type": "command", "command": prefix + " subagent-start"}}},
+ },
+ "SubagentStop": {
+ {"hooks": []map[string]interface{}{{"type": "command", "command": prefix + " subagent-stop"}}},
+ },
+ "PermissionRequest": {
+ {"matcher": "*", "hooks": []map[string]interface{}{{"type": "command", "command": prefix + " permission-request"}}},
+ },
+ "SessionEnd": {
+ {"hooks": []map[string]interface{}{{"type": "command", "command": prefix + " session-end"}}},
+ },
+ }
+ out := map[string]interface{}{"hooks": hooks}
+ data, _ := json.MarshalIndent(out, "", " ")
+ return string(data) + "\n"
+}
+
+func renderClaudeWebSetup(version string) string {
+ return fmt.Sprintf(`set -euo pipefail
+mkdir -p /tmp/beacon/bin /tmp/beacon/logs
+
+BEACON_VERSION=%q
+OS="linux"
+case "$(uname -m)" in
+ x86_64|amd64) ARCH="amd64" ;;
+ aarch64|arm64) ARCH="arm64" ;;
+ *) echo "unsupported arch $(uname -m)" >&2; exit 1 ;;
+esac
+
+ARCHIVE="beacon_${BEACON_VERSION#v}_${OS}_${ARCH}.tar.gz"
+BASE="https://github.com/asymptote-labs/agent-beacon/releases/download/${BEACON_VERSION}"
+curl -fsSL "${BASE}/${ARCHIVE}" -o "/tmp/beacon/${ARCHIVE}"
+tar -xzf "/tmp/beacon/${ARCHIVE}" -C /tmp/beacon/bin
+chmod +x /tmp/beacon/bin/beacon /tmp/beacon/bin/beacon-hooks 2>/dev/null || true
+
+mkdir -p .claude
+/tmp/beacon/bin/beacon cloud claude-web print-hooks \
+ --binary-path /tmp/beacon/bin/beacon-hooks \
+ --log-path /tmp/beacon/runtime.jsonl > .claude/settings.json
+`, version)
+}
+
+func runCloudGCSSetup(cmd *cobra.Command, args []string) error {
+ if cloudOpts.project == "" {
+ return fmt.Errorf("--project is required")
+ }
+ if cloudOpts.bucket == "" {
+ return fmt.Errorf("--bucket is required")
+ }
+ if !cloudOpts.apply && !cloudOpts.printOnly {
+ return fmt.Errorf("choose --print to review commands or --apply to run them")
+ }
+ email := serviceAccountEmail(cloudOpts.serviceAccount, cloudOpts.project)
+ commands := gcsSetupCommands(cloudOpts.project, cloudOpts.bucket, cloudOpts.location, email, serviceAccountID(cloudOpts.serviceAccount))
+ if cloudOpts.printOnly {
+ for _, command := range commands {
+ fmt.Println(shellCommand(command...))
+ }
+ }
+ if !cloudOpts.apply {
+ return nil
+ }
+ for _, command := range commands {
+ if err := runGCloud(command...); err != nil {
+ return err
+ }
+ }
+ if cloudOpts.printEnv {
+ keyPath, cleanup, err := createServiceAccountKey(cloudOpts.project, email)
+ if err != nil {
+ return err
+ }
+ defer cleanup()
+ data, err := os.ReadFile(keyPath)
+ if err != nil {
+ return err
+ }
+ fmt.Printf("BEACON_CLOUD_GCS_BUCKET=%s\n", cloudOpts.bucket)
+ fmt.Printf("BEACON_CLOUD_GCS_PREFIX=%s\n", strings.Trim(cloudOpts.prefix, "/"))
+ fmt.Printf("BEACON_CLOUD_GCS_CREDENTIALS_B64=%s\n", base64.StdEncoding.EncodeToString(data))
+ }
+ return nil
+}
+
+func gcsSetupCommands(project, bucket, location, email, accountID string) [][]string {
+ return [][]string{
+ {"gcloud", "services", "enable", "storage.googleapis.com", "iam.googleapis.com", "--project", project},
+ {"gcloud", "storage", "buckets", "describe", "gs://" + bucket, "--project", project},
+ {"gcloud", "storage", "buckets", "create", "gs://" + bucket, "--project", project, "--location", location, "--uniform-bucket-level-access"},
+ {"gcloud", "iam", "service-accounts", "describe", email, "--project", project},
+ {"gcloud", "iam", "service-accounts", "create", accountID, "--project", project, "--display-name", "Beacon cloud trace uploader"},
+ {"gcloud", "storage", "buckets", "add-iam-policy-binding", "gs://" + bucket, "--member", "serviceAccount:" + email, "--role", "roles/storage.objectUser"},
+ }
+}
+
+func runGCloud(args ...string) error {
+ // Some setup commands are idempotent checks followed by creates. If a describe
+ // succeeds, the matching create may fail with AlreadyExists; ignore only that
+ // common case so reruns remain simple for self-serve trials.
+ if len(args) >= 5 && args[0] == "gcloud" && args[2] == "buckets" && args[3] == "describe" {
+ if err := exec.Command(args[0], args[1:]...).Run(); err == nil {
+ return nil
+ }
+ return nil
+ }
+ if len(args) >= 5 && args[0] == "gcloud" && args[1] == "iam" && args[2] == "service-accounts" && args[3] == "describe" {
+ if err := exec.Command(args[0], args[1:]...).Run(); err == nil {
+ return nil
+ }
+ return nil
+ }
+ output, err := runGCloudCommand(args...)
+ if err != nil {
+ text := strings.TrimSpace(string(output))
+ if isAlreadyExistsOutput(text) {
+ return nil
+ }
+ if isGCSBucketIAMBinding(args) && serviceAccountNotPropagated(text) {
+ var lastOutput []byte
+ var lastErr error
+ for i := 0; i < 6; i++ {
+ time.Sleep(time.Duration(i+1) * 5 * time.Second)
+ lastOutput, lastErr = runGCloudCommand(args...)
+ if lastErr == nil {
+ return nil
+ }
+ if !serviceAccountNotPropagated(strings.TrimSpace(string(lastOutput))) {
+ break
+ }
+ }
+ if lastErr != nil {
+ return fmt.Errorf("%s failed after waiting for service account propagation: %w\n%s", shellCommand(args...), lastErr, strings.TrimSpace(string(lastOutput)))
+ }
+ }
+ return fmt.Errorf("%s failed: %w\n%s", shellCommand(args...), err, text)
+ }
+ return nil
+}
+
+func runGCloudCommand(args ...string) ([]byte, error) {
+ return exec.Command(args[0], args[1:]...).CombinedOutput()
+}
+
+func isAlreadyExistsOutput(text string) bool {
+ lower := strings.ToLower(text)
+ return strings.Contains(lower, "already exists") ||
+ strings.Contains(lower, "already own it") ||
+ strings.Contains(lower, "alreadyexists")
+}
+
+func isGCSBucketIAMBinding(args []string) bool {
+ return len(args) >= 5 &&
+ args[0] == "gcloud" &&
+ args[1] == "storage" &&
+ args[2] == "buckets" &&
+ args[3] == "add-iam-policy-binding"
+}
+
+func serviceAccountNotPropagated(text string) bool {
+ lower := strings.ToLower(text)
+ return strings.Contains(lower, "service account") && strings.Contains(lower, "does not exist")
+}
+
+func createServiceAccountKey(project, email string) (string, func(), error) {
+ dir, err := os.MkdirTemp("", "beacon-cloud-gcs-")
+ if err != nil {
+ return "", func() {}, err
+ }
+ cleanup := func() { _ = os.RemoveAll(dir) }
+ keyPath := filepath.Join(dir, "uploader.json")
+ args := []string{"gcloud", "iam", "service-accounts", "keys", "create", keyPath, "--iam-account", email, "--project", project}
+ output, err := exec.Command(args[0], args[1:]...).CombinedOutput()
+ if err != nil {
+ cleanup()
+ return "", func() {}, fmt.Errorf("%s failed: %w\n%s", shellCommand(args...), err, strings.TrimSpace(string(output)))
+ }
+ return keyPath, cleanup, nil
+}
+
+func serviceAccountEmail(value, project string) string {
+ value = strings.TrimSpace(value)
+ if strings.Contains(value, "@") {
+ return value
+ }
+ return value + "@" + project + ".iam.gserviceaccount.com"
+}
+
+func serviceAccountID(value string) string {
+ value = strings.TrimSpace(value)
+ if before, _, ok := strings.Cut(value, "@"); ok {
+ return before
+ }
+ return value
+}
+
+func shellCommand(args ...string) string {
+ parts := make([]string, 0, len(args))
+ for _, arg := range args {
+ parts = append(parts, shellQuote(arg))
+ }
+ return strings.Join(parts, " ")
+}
+
+func shellQuote(value string) string {
+ if value == "" {
+ return "''"
+ }
+ if strings.IndexFunc(value, func(r rune) bool {
+ return !(r == '-' || r == '_' || r == '.' || r == '/' || r == ':' || r == '@' || r == '=' || r == ',' || (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') || (r >= '0' && r <= '9'))
+ }) == -1 {
+ return value
+ }
+ return "'" + strings.ReplaceAll(value, "'", "'\\''") + "'"
+}
diff --git a/cli/beacon/cmd/cloud_test.go b/cli/beacon/cmd/cloud_test.go
new file mode 100644
index 00000000..adc10f51
--- /dev/null
+++ b/cli/beacon/cmd/cloud_test.go
@@ -0,0 +1,55 @@
+package cmd
+
+import (
+ "strings"
+ "testing"
+)
+
+func TestCloudCommandsRegistered(t *testing.T) {
+ for _, path := range [][]string{
+ {"cloud", "claude-web", "print-hooks"},
+ {"cloud", "claude-web", "print-setup"},
+ {"cloud", "gcs", "setup"},
+ } {
+ cmd, _, err := rootCmd.Find(path)
+ if err != nil {
+ t.Fatalf("Find %v returned error: %v", path, err)
+ }
+ if cmd == nil || cmd.Use != path[len(path)-1] {
+ t.Fatalf("cloud command %v not registered: %#v", path, cmd)
+ }
+ }
+}
+
+func TestRenderClaudeWebHooks(t *testing.T) {
+ got := renderClaudeWebHooks("/tmp/beacon/bin/beacon-hooks", "/tmp/beacon/runtime.jsonl")
+ for _, want := range []string{
+ `"SessionStart"`,
+ `"UserPromptSubmit"`,
+ `"PreToolUse"`,
+ `"PostToolUse"`,
+ `"Stop"`,
+ `"SessionEnd"`,
+ `BEACON_ENDPOINT_MODE=1`,
+ `BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl`,
+ `/tmp/beacon/bin/beacon-hooks --platform claude`,
+ } {
+ if !strings.Contains(got, want) {
+ t.Fatalf("rendered hooks missing %q:\n%s", want, got)
+ }
+ }
+}
+
+func TestGCSSetupCommands(t *testing.T) {
+ commands := gcsSetupCommands("asymptote-code", "bucket", "us-central1", "[email protected]", "uploader")
+ got := shellCommand(commands[len(commands)-1]...)
+ for _, want := range []string{
+ "gcloud storage buckets add-iam-policy-binding gs://bucket",
+ "serviceAccount:[email protected]",
+ "roles/storage.objectUser",
+ } {
+ if !strings.Contains(got, want) {
+ t.Fatalf("setup command missing %q: %s", want, got)
+ }
+ }
+}
diff --git a/examples/cloud-agents/claude-web-gcs.md b/examples/cloud-agents/claude-web-gcs.md
new file mode 100644
index 00000000..04f25190
--- /dev/null
+++ b/examples/cloud-agents/claude-web-gcs.md
@@ -0,0 +1,116 @@
+# Claude Code Web to GCS Telemetry
+
+This guide captures Beacon cloud-agent telemetry from Claude Code on the web and
+uploads a readable per-run `runtime.jsonl` object to a customer-managed GCS
+bucket.
+
+The flow is local-only inside the cloud sandbox until upload time:
+
+1. Claude Code on the web starts a cloud VM and clones the repository.
+2. The Claude environment setup script installs Beacon hook tooling into
+ `/tmp/beacon/bin`.
+3. Project-level `.claude/settings.json` is generated inside the sandbox clone.
+4. Hooks write Beacon JSONL to `/tmp/beacon/runtime.jsonl`.
+5. Beacon periodically uploads the latest snapshot to GCS.
+
+## 1. Prepare GCS
+
+Run this from a workstation with `gcloud` access to the target project:
+
+```bash
+gcloud config set project asymptote-code
+
+export BEACON_TEST_BUCKET="asymptote-beacon-cloud-agent-traces-test"
+export BEACON_TEST_LOCATION="us-central1"
+export BEACON_CLOUD_GCS_PREFIX="agent-traces/customer=asymptote-test"
+
+beacon cloud gcs setup \
+ --project asymptote-code \
+ --bucket "${BEACON_TEST_BUCKET}" \
+ --location "${BEACON_TEST_LOCATION}" \
+ --prefix "${BEACON_CLOUD_GCS_PREFIX}" \
+ --service-account beacon-cloud-trace-uploader \
+ --print
+
+beacon cloud gcs setup \
+ --project asymptote-code \
+ --bucket "${BEACON_TEST_BUCKET}" \
+ --location "${BEACON_TEST_LOCATION}" \
+ --prefix "${BEACON_CLOUD_GCS_PREFIX}" \
+ --service-account beacon-cloud-trace-uploader \
+ --apply \
+ --print-env
+```
+
+Copy the printed `BEACON_CLOUD_GCS_*` values into the Claude Code web
+environment.
+
+## 2. Configure Claude Web
+
+In `claude.ai/code`, edit the target repository's cloud environment.
+
+Set network access so the sandbox can reach `storage.googleapis.com`.
+
+Add environment variables:
+
+```bash
+BEACON_ORIGIN=cloud
+BEACON_RUN_PROVIDER=claude_code_web
+BEACON_RUN_EPHEMERAL=true
+BEACON_CLOUD_USER_ID_HASH=<stable-user-or-test-hash>
+BEACON_CLOUD_GCS_BUCKET=<bucket>
+BEACON_CLOUD_GCS_PREFIX=<prefix>
+BEACON_CLOUD_GCS_CREDENTIALS_B64=<base64-service-account-json>
+BEACON_CLOUD_UPLOAD_INTERVAL=60s
+```
+
+Add this setup script, replacing `vX.Y.Z` with a Beacon release that includes
+cloud-agent support:
+
+```bash
+set -euo pipefail
+mkdir -p /tmp/beacon/bin /tmp/beacon/logs
+
+BEACON_VERSION="vX.Y.Z"
+OS="linux"
+case "$(uname -m)" in
+ x86_64|amd64) ARCH="amd64" ;;
+ aarch64|arm64) ARCH="arm64" ;;
+ *) echo "unsupported arch $(uname -m)" >&2; exit 1 ;;
+esac
+
+ARCHIVE="beacon_${BEACON_VERSION#v}_${OS}_${ARCH}.tar.gz"
+BASE="https://github.com/asymptote-labs/agent-beacon/releases/download/${BEACON_VERSION}"
+curl -fsSL "${BASE}/${ARCHIVE}" -o "/tmp/beacon/${ARCHIVE}"
+tar -xzf "/tmp/beacon/${ARCHIVE}" -C /tmp/beacon/bin
+chmod +x /tmp/beacon/bin/beacon /tmp/beacon/bin/beacon-hooks
+
+mkdir -p .claude
+/tmp/beacon/bin/beacon cloud claude-web print-hooks \
+ --binary-path /tmp/beacon/bin/beacon-hooks \
+ --log-path /tmp/beacon/runtime.jsonl > .claude/settings.json
+```
+
+The generated `.claude/settings.json` lives only in the cloud sandbox clone
+unless the agent explicitly commits it.
+
+## 3. Run and Verify
+
+Start a Claude Code web task that uses tools, for example:
+
+```text
+Read the README, run pwd && ls, create a tiny temporary markdown note, then summarize what you did.
+```
+
+Verify the uploaded JSONL:
+
+```bash
+gcloud storage ls "gs://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_GCS_PREFIX}/provider=claude_code_web/"
+gcloud storage cp "gs://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_GCS_PREFIX}/provider=claude_code_web/**/runtime.jsonl" /tmp/beacon-cloud-runtime.jsonl
+head -20 /tmp/beacon-cloud-runtime.jsonl
+```
+
+Expected fields include `vendor=beacon`, `product=endpoint-agent`,
+`schema_version=1.0`, `origin=cloud`, `harness.name=claude`,
+`run.provider=claude_code_web`, and a `run.run_id` matching the Claude remote
+session ID when available.