The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
Capture Cursor Cloud prompts in object storage
shukieshahdddefb1847d1
diff --git a/.cursor/environment.json b/.cursor/environment.jsonindex 4a7fd055..bb6e73ec 100644--- a/.cursor/environment.json+++ b/.cursor/environment.json@@ -1,5 +1,4 @@{- "image": "ubuntu-22.04","install": "./.cursor/install.sh","start": "./.cursor/start.sh"}diff --git a/.cursor/hooks.json b/.cursor/hooks.jsonindex cd1d310d..3520ec5f 100644--- a/.cursor/hooks.json+++ b/.cursor/hooks.json@@ -3,47 +3,53 @@"hooks": {"afterFileEdit": [{- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor post-tool"+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor post-tool"}],"afterShellExecution": [{- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor post-tool"+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor post-tool"}],"beforeReadFile": [{- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor pre-tool"+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor pre-tool"}],"beforeShellExecution": [{- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor pre-tool"+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor pre-tool"+ }+ ],+ "beforeSubmitPrompt": [+ {+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor prompt-submit",+ "timeout": 30}],"postToolUse": [{- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor post-tool"+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor post-tool"}],"postToolUseFailure": [{- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor post-tool"+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor post-tool"}],"preCompact": [{- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor cursor-event"+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor cursor-event"}],"subagentStart": [{- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor subagent-start"+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor subagent-start"}],"subagentStop": [{- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor subagent-stop"+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor subagent-stop"}]}diff --git a/.cursor/install.sh b/.cursor/install.shindex ae85122c..5991b092 100755--- a/.cursor/install.sh+++ b/.cursor/install.sh@@ -50,8 +50,10 @@ install_go() {build_from_source() {install_go- (cd "$REPO_ROOT/cli/beacon" && go build -o "$BEACON_BIN_DIR/beacon" .)+ export GOTOOLCHAIN="${GOTOOLCHAIN:-auto}"(cd "$REPO_ROOT/cli/beacon-hooks" && go build -o "$BEACON_BIN_DIR/beacon-hooks" .)+ cp "$BEACON_BIN_DIR/beacon-hooks" "$REPO_ROOT/cli/beacon/internal/embedded/hooks.bin"+ (cd "$REPO_ROOT/cli/beacon" && go build -o "$BEACON_BIN_DIR/beacon" .)}if [ -n "${BEACON_VERSION:-}" ]; thendiff --git a/.cursor/start.sh b/.cursor/start.shindex 0c5a1971..25b9b55a 100755--- a/.cursor/start.sh+++ b/.cursor/start.sh@@ -6,10 +6,26 @@ BEACON_LOG_PATH="${BEACON_CLOUD_LOG_PATH:-$BEACON_HOME/runtime.jsonl}"mkdir -p "$(dirname "$BEACON_LOG_PATH")"-if [ -n "${BEACON_CLOUD_GCS_BUCKET:-}" ] && [ -n "${BEACON_CLOUD_GCS_CREDENTIALS_B64:-}" ]; then- echo "Beacon Cloud GCS forwarding is configured for bucket: $BEACON_CLOUD_GCS_BUCKET"-else- echo "Beacon Cloud GCS forwarding is not active; set BEACON_CLOUD_GCS_BUCKET and BEACON_CLOUD_GCS_CREDENTIALS_B64 to enable uploads."-fi+case "${BEACON_CLOUD_UPLOAD:-gcs}" in+ s3)+ if [ -n "${BEACON_CLOUD_S3_BUCKET:-}" ] &&+ [ -n "${AWS_ACCESS_KEY_ID:-}" ] &&+ [ -n "${AWS_SECRET_ACCESS_KEY:-}" ]; then+ echo "Beacon Cloud S3 forwarding is configured for bucket: $BEACON_CLOUD_S3_BUCKET"+ else+ echo "Beacon Cloud S3 forwarding is not active; set the S3 bucket, region, and AWS credentials to enable uploads."+ fi+ ;;+ gcs)+ if [ -n "${BEACON_CLOUD_GCS_BUCKET:-}" ] && [ -n "${BEACON_CLOUD_GCS_CREDENTIALS_B64:-}" ]; then+ echo "Beacon Cloud GCS forwarding is configured for bucket: $BEACON_CLOUD_GCS_BUCKET"+ else+ echo "Beacon Cloud GCS forwarding is not active; set the GCS bucket and credentials to enable uploads."+ fi+ ;;+ *)+ echo "Beacon Cloud forwarding has unsupported BEACON_CLOUD_UPLOAD=${BEACON_CLOUD_UPLOAD}."+ ;;+esacecho "Beacon runtime log path: $BEACON_LOG_PATH"diff --git a/cli/beacon-hooks/cmd/prompt_submit.go b/cli/beacon-hooks/cmd/prompt_submit.goindex b5011db2..18ece901 100644--- a/cli/beacon-hooks/cmd/prompt_submit.go+++ b/cli/beacon-hooks/cmd/prompt_submit.go@@ -54,5 +54,6 @@ func runPromptSubmit(cmd *cobra.Command, args []string) {}}+ maybeUploadCursorCloudTelemetry(logger)outputJSON(hookNoopResponse())}diff --git a/cli/beacon-hooks/cmd/prompt_submit_cloud_test.go b/cli/beacon-hooks/cmd/prompt_submit_cloud_test.gonew file mode 100644index 00000000..da8d36e6--- /dev/null+++ b/cli/beacon-hooks/cmd/prompt_submit_cloud_test.go@@ -0,0 +1,93 @@+package cmd++import (+ "compress/gzip"+ "encoding/json"+ "io"+ "net/http"+ "net/http/httptest"+ "path/filepath"+ "strings"+ "testing"+)++func TestRunPromptSubmitUploadsCursorCloudTelemetryToS3(t *testing.T) {+ setupHookConfigDirs(t)+ platformFlag = "cursor"++ uploaded := make(chan []byte, 1)+ var uploadPath string+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ if r.Method != http.MethodPut {+ t.Errorf("method = %s, want PUT", r.Method)+ }+ if r.Header.Get("Content-Encoding") != "gzip" {+ t.Errorf("Content-Encoding = %q, want gzip", r.Header.Get("Content-Encoding"))+ }+ if !strings.HasPrefix(r.Header.Get("Authorization"), "AWS4-HMAC-SHA256 ") {+ t.Errorf("Authorization = %q, want SigV4", r.Header.Get("Authorization"))+ }+ uploadPath = r.URL.Path+ reader, err := gzip.NewReader(r.Body)+ if err != nil {+ t.Errorf("open gzip body: %v", err)+ w.WriteHeader(http.StatusBadRequest)+ return+ }+ defer reader.Close()+ body, err := io.ReadAll(reader)+ if err != nil {+ t.Errorf("read gzip body: %v", err)+ w.WriteHeader(http.StatusBadRequest)+ return+ }+ uploaded <- body+ w.WriteHeader(http.StatusOK)+ }))+ defer server.Close()++ tempDir := t.TempDir()+ logPath := filepath.Join(tempDir, "runtime.jsonl")+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)+ t.Setenv("BEACON_CLOUD_SHUTTLE_STATE", filepath.Join(tempDir, "shuttle-state.json"))+ t.Setenv("BEACON_ORIGIN", "cloud")+ t.Setenv("BEACON_RUN_PROVIDER", "cursor_cloud")+ t.Setenv("BEACON_RUN_ID", "")+ t.Setenv("BEACON_CLOUD_UPLOAD", "s3")+ t.Setenv("BEACON_CLOUD_S3_BUCKET", "telemetry-bucket")+ t.Setenv("BEACON_CLOUD_S3_PREFIX", "agent-traces")+ t.Setenv("BEACON_CLOUD_S3_REGION", "us-east-1")+ t.Setenv("BEACON_CLOUD_S3_ENDPOINT", server.URL)+ t.Setenv("AWS_ACCESS_KEY_ID", "AKIATEST")+ t.Setenv("AWS_SECRET_ACCESS_KEY", "test-secret")++ out := runHookWithInput(t, runPromptSubmit, map[string]interface{}{+ "conversation_id": "conv-prompt",+ "hook_event_name": "beforeSubmitPrompt",+ "prompt": "Summarize this repository",+ "cwd": "/workspace",+ })+ if out["continue"] != true {+ t.Fatalf("prompt response = %#v, want continue=true", out)+ }++ body := <-uploaded+ var event map[string]interface{}+ if err := json.Unmarshal(body, &event); err != nil {+ t.Fatalf("unmarshal uploaded event: %v\n%s", err, body)+ }+ if action := event["event"].(map[string]interface{})["action"]; action != "prompt.submitted" {+ t.Fatalf("event.action = %q, want prompt.submitted", action)+ }+ if prompt := event["prompt"].(map[string]interface{})["text"]; prompt != "Summarize this repository" {+ t.Fatalf("prompt.text = %q", prompt)+ }+ run := event["run"].(map[string]interface{})+ if run["provider"] != "cursor_cloud" || run["run_id"] != "conv-prompt" {+ t.Fatalf("run = %#v", run)+ }+ if !strings.Contains(uploadPath, "/telemetry-bucket/agent-traces/runtime/") ||+ !strings.HasSuffix(uploadPath, "-cursor_cloud-conv-prompt.jsonl.gz") {+ t.Fatalf("upload path = %q", uploadPath)+ }+}diff --git a/cli/beacon/cmd/cloud_test.go b/cli/beacon/cmd/cloud_test.goindex f6a39fbb..e5e99b9b 100644--- a/cli/beacon/cmd/cloud_test.go+++ b/cli/beacon/cmd/cloud_test.go@@ -42,6 +42,8 @@ func TestRenderCursorCloudHooks(t *testing.T) {`"postToolUseFailure"`,`"beforeShellExecution"`,`"afterShellExecution"`,+ `"beforeSubmitPrompt"`,+ `prompt-submit`,`"beforeReadFile"`,`"afterFileEdit"`,`"subagentStart"`,@@ -55,7 +57,7 @@ func TestRenderCursorCloudHooks(t *testing.T) {t.Fatalf("rendered hooks missing %q:\n%s", want, got)}}- for _, unsupported := range []string{`"preToolUse"`, `"sessionStart"`, `"sessionEnd"`, `"beforeSubmitPrompt"`, `"stop"`} {+ for _, unsupported := range []string{`"preToolUse"`, `"sessionStart"`, `"sessionEnd"`, `"stop"`} {if strings.Contains(got, unsupported) {t.Fatalf("rendered cursor cloud hooks should not contain %q:\n%s", unsupported, got)}@@ -72,6 +74,7 @@ func TestRenderCursorCloudSafeHooks(t *testing.T) {t.Fatalf("render cursor cloud hooks: %v", err)}for _, want := range []string{+ `"beforeSubmitPrompt"`,`"beforeReadFile"`,`"postToolUse"`,`"subagentStart"`,diff --git a/cli/beacon/internal/endpoint/hooks/cursor.go b/cli/beacon/internal/endpoint/hooks/cursor.goindex f23b20d4..e2b64085 100644--- a/cli/beacon/internal/endpoint/hooks/cursor.go+++ b/cli/beacon/internal/endpoint/hooks/cursor.go@@ -130,6 +130,7 @@ func CursorCloudHookRefs(opts CursorCloudOptions) map[string][]HookRef {}prefix := cursorCloudCommandPrefix(opts.BinaryPath, opts.LogPath)refs := map[string][]HookRef{+ "beforeSubmitPrompt": {{Command: prefix + " prompt-submit", Timeout: 30}},"postToolUse": {{Command: prefix + " post-tool"}},"postToolUseFailure": {{Command: prefix + " post-tool"}},"beforeReadFile": {diff --git a/docs/cli/cloud-cursor-print-hooks.mdx b/docs/cli/cloud-cursor-print-hooks.mdxindex ed452cc3..fe72754c 100644--- a/docs/cli/cloud-cursor-print-hooks.mdx+++ b/docs/cli/cloud-cursor-print-hooks.mdx@@ -17,16 +17,17 @@ The rendered hooks set `BEACON_ORIGIN=cloud`, `BEACON_RUN_PROVIDER=cursor_cloud`Cursor Cloud only runs command-based project hooks after the cloud VM starts.The generated hook set uses supported Cursor Cloud hooks such as-`beforeReadFile`, `beforeShellExecution`, `afterShellExecution`,+`beforeSubmitPrompt`, `beforeReadFile`, `beforeShellExecution`, `afterShellExecution`,`afterFileEdit`, `postToolUse`, `postToolUseFailure`, `subagentStart`,-`subagentStop`, and `preCompact`. It does not include broad `preToolUse`,-`beforeSubmitPrompt`, `sessionStart`, `sessionEnd`, or `stop` because Cursor-does not run those hooks in cloud agents. See+`subagentStop`, and `preCompact`. It currently omits broad `preToolUse`,+`sessionStart`, `sessionEnd`, and `stop`. See[Cursor's Cloud Agent hook support matrix](https://cursor.com/docs/hooks#cloud-agent-support)for the current platform support list.Beacon uses Cursor's `conversation_id` hook payload as the default`run.run_id` for Cursor Cloud telemetry unless `BEACON_RUN_ID` is already set.+Prompt events are written and uploaded as soon as `beforeSubmitPrompt` runs,+including prompt-only follow-up turns.## Examplesdiff --git a/docs/cli/cloud-cursor-print-setup.mdx b/docs/cli/cloud-cursor-print-setup.mdxindex 526dc9e4..68b8d342 100644--- a/docs/cli/cloud-cursor-print-setup.mdx+++ b/docs/cli/cloud-cursor-print-setup.mdx@@ -20,9 +20,11 @@ project hooks with [`beacon cloud cursor print-hooks`](/cli/cloud-cursor-print-hcommit `.cursor/hooks.json` to the repository, then start Cursor Cloud Agentsfrom a commit that contains that file.-Cursor cloud agents do not run prompt or session lifecycle hooks such as-`beforeSubmitPrompt`, `sessionStart`, `sessionEnd`, and `stop`. Beacon refreshes-the uploaded `runtime.jsonl` object as supported hook events run. See+Cursor Cloud Agents run the committed `beforeSubmitPrompt` project hook after+the cloud environment is available, so Beacon can capture and immediately+upload prompt events. `sessionStart` and `sessionEnd` remain unavailable in+Cursor Cloud. Beacon refreshes the uploaded `runtime.jsonl` object as supported+hook events run. See[Cursor's Cloud Agent hook support matrix](https://cursor.com/docs/hooks#cloud-agent-support)for the current platform support list.diff --git a/docs/runtimes/cursor-cloud-agents.mdx b/docs/runtimes/cursor-cloud-agents.mdxindex 3110a7b6..74f37f81 100644--- a/docs/runtimes/cursor-cloud-agents.mdx+++ b/docs/runtimes/cursor-cloud-agents.mdx@@ -1,12 +1,12 @@---title: "Cursor Cloud Agents"-description: "Capture Cursor cloud agent telemetry and forward cloud-agent runtime logs to customer-managed Google Cloud Storage"+description: "Capture Cursor cloud agent telemetry and forward cloud-agent runtime logs to customer-managed Google Cloud Storage or Amazon S3"---## Integration OverviewUse this integration to capture Cursor cloud-agent activity and upload each-session log to your own Google Cloud Storage bucket. It is meant for testing+session log to your own Google Cloud Storage or Amazon S3 bucket. It is meant for testingcloud-agent telemetry without running a hosted Asymptote backend.This flow depends on the Beacon CLI. You run `beacon cloud` commands from your@@ -33,12 +33,12 @@ object as supported Cursor hook events run.flowchart LRCursorCloud["Cursor Cloud Agents"] --> Hooks["Beacon hooks in sandbox"]Hooks --> RuntimeLog["/tmp/beacon/runtime.jsonl"]- RuntimeLog --> GCS["Customer-managed GCS bucket"]+ RuntimeLog --> Storage["Customer-managed GCS or S3 bucket"]```The setup has four parts:-1. Create a dedicated GCS bucket and uploader service account with Beacon.+1. Create a dedicated GCS or S3 upload path with Beacon.2. Add Beacon cloud telemetry environment variables to the Cursor cloud environment.3. Commit Beacon's project-level Cursor hooks to `.cursor/hooks.json`.4. Run a Beacon-generated setup script inside the Cursor cloud environment to@@ -50,6 +50,12 @@ Each Cursor cloud agent conversation writes one readable JSONL object:gs://<bucket>/<prefix>/runtime/date=YYYY-MM-DD/<timestamp>-cursor_cloud-<cursor_conversation_id>.jsonl.gz```+or:++```text+s3://<bucket>/<prefix>/runtime/date=YYYY-MM-DD/<timestamp>-cursor_cloud-<cursor_conversation_id>.jsonl.gz+```+Beacon uses Cursor's `conversation_id` hook field as the default `run_id` forCursor Cloud telemetry. If you set `BEACON_RUN_ID` yourself, Beacon preservesthat value instead.@@ -57,14 +63,15 @@ that value instead.## Prerequisites- Beacon CLI `v0.0.56` or later.-- `gcloud` installed and authenticated to the Google Cloud project you will use- for telemetry storage.-- A Google Cloud project where you can create buckets, service accounts, IAM- bindings, and service account keys.+- For GCS: `gcloud` installed and authenticated to a project where you can+ create buckets, service accounts, IAM bindings, and service account keys.+- For S3: AWS CLI installed and authenticated to an account where you can+ create buckets, IAM users, inline policies, and access keys.- Cursor Cloud Agent access for the repository you want to test.- A Cursor cloud environment with outbound access to:- `oauth2.googleapis.com`- `storage.googleapis.com`+ - `s3.<region>.amazonaws.com`- `github.com`- `*.githubusercontent.com`@@ -84,7 +91,11 @@ gcloud auth logingcloud config set project <your-gcp-project>```-## 1. Create the GCS Upload Path+## 1. Create the Object Storage Upload Path++Choose GCS or S3 for the cloud-agent session logs.++### GCSFrom your workstation, choose a bucket and prefix:@@ -133,6 +144,42 @@ share screenshots or logs.The helper creates a dedicated uploader service account and grants it objectupload access to the selected bucket.+### S3++From your workstation, choose a bucket, region, and prefix:++```bash+export AWS_REGION="us-east-1"+export BEACON_TEST_BUCKET="your-beacon-cloud-agent-traces"+export BEACON_CLOUD_S3_PREFIX="agent-traces/customer=my-team"+```++Review the AWS changes Beacon will make:++```bash+beacon cloud s3 setup \+ --bucket "$BEACON_TEST_BUCKET" \+ --region "$AWS_REGION" \+ --prefix "$BEACON_CLOUD_S3_PREFIX" \+ --iam-user beacon-cloud-trace-uploader \+```++Apply the setup and print the cloud telemetry environment variables:++```bash+beacon cloud s3 setup \+ --bucket "$BEACON_TEST_BUCKET" \+ --region "$AWS_REGION" \+ --prefix "$BEACON_CLOUD_S3_PREFIX" \+ --iam-user beacon-cloud-trace-uploader \+ --apply \+ --print-env+```++The helper creates a dedicated IAM user and grants it `s3:PutObject` only under+the selected bucket prefix.+## 2. Configure Cursor Cloud AgentsOpen your Cursor Cloud Agent environment for the repository.@@ -144,11 +191,27 @@ BEACON_ORIGIN=cloudBEACON_RUN_PROVIDER=cursor_cloudBEACON_RUN_EPHEMERAL=trueBEACON_CLOUD_USER_ID_HASH=<stable-user-or-test-id>+```++For GCS, add:++```bashBEACON_CLOUD_GCS_BUCKET=<bucket-from-setup>BEACON_CLOUD_GCS_PREFIX=<prefix-from-setup>BEACON_CLOUD_GCS_CREDENTIALS_B64=<base64-service-account-json>```+For S3, add:++```bash+BEACON_CLOUD_UPLOAD=s3+BEACON_CLOUD_S3_BUCKET=<bucket-from-setup>+BEACON_CLOUD_S3_PREFIX=<prefix-from-setup>+BEACON_CLOUD_S3_REGION=<region-from-setup>+AWS_ACCESS_KEY_ID=<access-key-id-from-setup>+AWS_SECRET_ACCESS_KEY=<secret-access-key-from-setup>+```+<Frame caption="Configure network access and Beacon runtime secrets for Cursor Cloud Agents."><img src="/images/cursor-cloud-agents/cursor-cloud-agent-config.png" alt="Cursor Cloud Agents settings showing network allowlist entries and Beacon runtime secrets for GCS upload." /></Frame>@@ -158,6 +221,7 @@ If your Cursor cloud environment restricts outbound network access, allow:```textoauth2.googleapis.comstorage.googleapis.com+s3.<region>.amazonaws.comgithub.com*.githubusercontent.com```@@ -223,22 +287,28 @@ file reads and edits, subagent lifecycle events, and compaction events whereCursor exposes hook payloads.<Note>- Cursor Cloud Agents do not run `beforeSubmitPrompt`, `sessionStart`,- `sessionEnd`, or `stop` hooks. Prompt text and final session lifecycle hooks- are therefore not available through this self-serve hook path; Beacon records- the supported in-sandbox events Cursor exposes after the cloud VM starts. See+ Beacon captures prompt text through Cursor Cloud's `beforeSubmitPrompt`+ project hook and uploads that event immediately. Commit `.cursor/hooks.json`+ before starting the run so the prompt hook is available when the cloud+ environment starts. `sessionStart` and `sessionEnd` remain unavailable. See[Cursor's Cloud Agent hook support matrix](https://cursor.com/docs/hooks#cloud-agent-support)for the current platform support list.</Note>-## 6. Verify GCS Upload+## 6. Verify Object Storage Upload-List the uploaded session objects:+For GCS, list the uploaded session objects:```bashgcloud storage ls --recursive "gs://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_GCS_PREFIX}/"```+For S3:++```bash+aws s3 ls --recursive "s3://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_S3_PREFIX}/"+```+You should see a path like:```text@@ -255,6 +325,12 @@ Inspect the log:gcloud storage cat "gs://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_GCS_PREFIX}/runtime/date=<date>/<object>.jsonl.gz" | gzip -dc | head```+For S3:++```bash+aws s3 cp "s3://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_S3_PREFIX}/runtime/date=<date>/<object>.jsonl.gz" - | gzip -dc | head+```+Expected fields include:```text@@ -268,10 +344,10 @@ run.provider=cursor_cloud## Security Note-The self-serve GCS flow above creates a dedicated service account scoped to-object uploads for one bucket, then stores its credentials in the Cursor cloud-environment. This is useful for proof-of-concept testing, but treat that-environment variable as a sensitive credential.+The self-serve flows create a dedicated GCS service account or AWS IAM user+scoped to object uploads, then store its credentials in the Cursor cloud+environment. This is useful for proof-of-concept testing, but treat those+environment variables as sensitive credentials.Avoid broad credentials and review access before using this flow with sensitivetelemetry.@@ -296,15 +372,14 @@ ls -l /tmp/beacon/runtime.jsonlhead /tmp/beacon/runtime.jsonl```-If `runtime.jsonl` exists but GCS is empty, check network access and GCS-credentials. The cloud sandbox must reach both `oauth2.googleapis.com` and-`storage.googleapis.com`.+If `runtime.jsonl` exists but object storage is empty, check network access and+credentials. The cloud sandbox must reach the GCS OAuth/storage endpoints or+the regional S3 endpoint selected by `BEACON_CLOUD_UPLOAD=s3`.If `runtime.jsonl` does not exist, confirm the task used a Cursor Cloud-supported hook surface such as a file read, shell command, file edit, tool use,-subagent event, or compaction event. Prompt-only tasks do not emit-`beforeSubmitPrompt` in Cursor Cloud because the prompt is submitted before the-cloud VM exists. Cursor documents the supported and unsupported cloud hooks in+supported hook surface such as prompt submission, a file read, shell command,+file edit, tool use, subagent event, or compaction event. Cursor documents the+supported and unsupported cloud hooks inits [Cloud Agent hook support matrix](https://cursor.com/docs/hooks#cloud-agent-support).### Cursor tries to commit hook settingsdiff --git a/docs/runtimes/cursor.mdx b/docs/runtimes/cursor.mdxindex cd2fa71f..1292e5a8 100644--- a/docs/runtimes/cursor.mdx+++ b/docs/runtimes/cursor.mdx@@ -47,7 +47,7 @@ beacon endpoint hooks install --harness cursor --level project| Area | Support ||------|---------|-| Prompt telemetry | Supported for local Cursor through `beforeSubmitPrompt` hooks; not available in Cursor Cloud Agents because Cursor submits the prompt before the cloud VM exists. See [Cursor's Cloud Agent hook support matrix](https://cursor.com/docs/hooks#cloud-agent-support). |+| Prompt telemetry | Supported for local and cloud Cursor through `beforeSubmitPrompt` hooks. Cursor Cloud requires the project hook to be committed before the run starts; Beacon uploads the prompt event immediately. See [Cursor's Cloud Agent hook support matrix](https://cursor.com/docs/hooks#cloud-agent-support). || Command, tool, and file telemetry | Supported for tool, shell command, MCP-like, approval, and file edit payloads where Cursor exposes them; Cursor Cloud support is limited to Cursor's [cloud-supported command hooks](https://cursor.com/docs/hooks#cloud-agent-support). || Agent reasoning telemetry | Supported for local Cursor through `afterAgentThought` hooks. Each completed thinking block is recorded as an `agent.reasoning` event carrying the reasoning text in the OpenTelemetry GenAI output-messages shape (`gen_ai.output.messages` with a `reasoning` part), plus a `content` marker with the original text's hash and byte count. Reasoning is only available for models/modes where Cursor exposes visible thinking text. || Repository and branch context | Events include the workspace path as `repository`, and `branch` is resolved from the workspace's local git checkout (`.git/HEAD`) when Cursor does not supply one; disable local git resolution with `BEACON_DISABLE_GIT_METADATA=1`. |