Skip to content

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

add cursor cloud agent support

Justin D'Souzaf257e374b9bc
diff --git a/cli/beacon-hooks/cmd/cursor_event.go b/cli/beacon-hooks/cmd/cursor_event.go
new file mode 100644
index 00000000..5834e034
--- /dev/null
+++ b/cli/beacon-hooks/cmd/cursor_event.go
@@ -0,0 +1,40 @@
+package cmd
+
+import (
+ "github.com/spf13/cobra"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/logging"
+)
+
+var cursorEventCmd = &cobra.Command{
+ Use: "cursor-event",
+ Short: "Record Cursor-specific lifecycle telemetry",
+ Run: runCursorEvent,
+}
+
+func init() {
+ rootCmd.AddCommand(cursorEventCmd)
+}
+
+func runCursorEvent(cmd *cobra.Command, args []string) {
+ input, err := readStdinJSON()
+ if err != nil {
+ outputJSON(emptyResponse)
+ return
+ }
+ sessionID := resolveSessionID(input, platformFlag)
+ var logger *logging.Logger
+ if sessionID != "" {
+ logger = logging.NewSessionLogger("cursor-event", platformFlag, sessionID)
+ } else {
+ logger = logging.NewLoggerForPlatform("cursor-event", platformFlag)
+ }
+ switch getFirstStr(input, "hook_event_name", "hookEventName") {
+ case "preCompact":
+ emitHookEvent(logger, "session.compacting", "session", "info", "Context compaction observed", input, sessionFields(sessionID, input))
+ default:
+ emitHookEvent(logger, "session.event", "session", "info", "Cursor lifecycle event observed", input, sessionFields(sessionID, input))
+ }
+ maybeUploadCursorCloudTelemetry(logger)
+ outputJSON(emptyResponse)
+}
diff --git a/cli/beacon-hooks/cmd/endpoint_events.go b/cli/beacon-hooks/cmd/endpoint_events.go
index 153ef6c4..62b64312 100644
--- a/cli/beacon-hooks/cmd/endpoint_events.go
+++ b/cli/beacon-hooks/cmd/endpoint_events.go
@@ -5,6 +5,7 @@ import (
"crypto/sha256"
"encoding/hex"
"fmt"
+ "os"
"path/filepath"
"strings"
"time"
@@ -52,6 +53,16 @@ func uploadCloudTelemetry(logger *logging.Logger, force bool) {
}
}
+func maybeUploadCursorCloudTelemetry(logger *logging.Logger) {
+ if platformFlag != "cursor" {
+ return
+ }
+ if strings.TrimSpace(os.Getenv("BEACON_ORIGIN")) != "cloud" || strings.TrimSpace(os.Getenv("BEACON_RUN_PROVIDER")) != "cursor_cloud" {
+ return
+ }
+ uploadCloudTelemetry(logger, true)
+}
+
func sessionFields(sessionID string, input map[string]interface{}) map[string]interface{} {
fields := map[string]interface{}{}
session := map[string]interface{}{}
diff --git a/cli/beacon-hooks/cmd/helpers.go b/cli/beacon-hooks/cmd/helpers.go
index 31662ee2..0f9736aa 100644
--- a/cli/beacon-hooks/cmd/helpers.go
+++ b/cli/beacon-hooks/cmd/helpers.go
@@ -60,7 +60,7 @@ func resolveSessionID(input map[string]interface{}, platform string) string {
}
return getFirstStr(input, "sessionId", "session_id")
case "cursor":
- return getFirstStr(input, "conversation_id")
+ return getFirstStr(input, "conversation_id", "parent_conversation_id")
case "vscode":
return getFirstStr(input, "sessionId", "session_id", "conversation_id", "gen_ai.conversation.id")
case "devin", "devin-cli":
diff --git a/cli/beacon-hooks/cmd/post_tool.go b/cli/beacon-hooks/cmd/post_tool.go
index 2096a96e..791f642e 100644
--- a/cli/beacon-hooks/cmd/post_tool.go
+++ b/cli/beacon-hooks/cmd/post_tool.go
@@ -65,6 +65,7 @@ func runPostTool(cmd *cobra.Command, args []string) {
hookEvent, _ := input["hook_event_name"].(string)
if hookEvent != "afterFileEdit" {
emitPostToolObserved(logger, input)
+ maybeUploadCursorCloudTelemetry(logger)
outputJSON(emptyResponse)
return
}
@@ -83,6 +84,7 @@ func runPostTool(cmd *cobra.Command, args []string) {
}
recordLocalEdit(params, logger)
+ maybeUploadCursorCloudTelemetry(logger)
outputJSON(emptyResponse)
}
@@ -280,6 +282,9 @@ func resolveToolResponse(input map[string]interface{}) map[string]interface{} {
}
func emitPostToolObserved(logger *logging.Logger, input map[string]interface{}) {
+ if platformFlag == "cursor" && emitCursorPostHookObserved(logger, input) {
+ return
+ }
toolName := getFirstStr(input, "tool_name", "toolName")
if platformFlag == "antigravity" {
toolName = antigravityToolName(input)
@@ -316,6 +321,41 @@ func emitPostToolObserved(logger *logging.Logger, input map[string]interface{})
emitHookEvent(logger, action, category, "info", message, input, fields)
}
+func emitCursorPostHookObserved(logger *logging.Logger, input map[string]interface{}) bool {
+ hookEvent := getFirstStr(input, "hook_event_name", "hookEventName")
+ sessionID := resolveSessionID(input, "cursor")
+ fields := sessionFields(sessionID, input)
+ switch hookEvent {
+ case "afterShellExecution":
+ command := getFirstStr(input, "command")
+ commandFields := map[string]interface{}{"command": command}
+ if output := getFirstStr(input, "output"); output != "" {
+ commandFields["output"] = output
+ }
+ if duration, ok := input["duration"]; ok {
+ commandFields["duration_ms"] = duration
+ }
+ fields["command"] = commandFields
+ emitHookEvent(logger, "command.executed", "command", "info", "Shell command executed", input, fields)
+ return true
+ case "postToolUseFailure":
+ toolName := getFirstStr(input, "tool_name", "toolName")
+ toolInput := resolveToolInput(input)
+ for key, value := range toolFields(toolName, toolInput) {
+ fields[key] = value
+ }
+ fields["tool"] = mergeNested(fields["tool"], map[string]interface{}{
+ "name": toolName,
+ "failure_type": getFirstStr(input, "failure_type"),
+ "error": getFirstStr(input, "error_message", "error"),
+ })
+ emitHookEvent(logger, "tool.failed", "tool", "high", "Tool execution failed", input, fields)
+ return true
+ default:
+ return false
+ }
+}
+
// isFileEditTool returns true if the tool name represents a file edit operation.
func isFileEditTool(platform, toolName string) bool {
if platform == "copilot" || platform == "vscode" {
diff --git a/cli/beacon-hooks/cmd/post_tool_test.go b/cli/beacon-hooks/cmd/post_tool_test.go
index bd0347a3..40586057 100644
--- a/cli/beacon-hooks/cmd/post_tool_test.go
+++ b/cli/beacon-hooks/cmd/post_tool_test.go
@@ -86,6 +86,68 @@ func TestRunPostToolEmitsAntigravityToolFailed(t *testing.T) {
}
}
+func TestRunPostToolEmitsCursorAfterShellExecution(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "cursor"
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ out := runHookWithInput(t, runPostTool, map[string]interface{}{
+ "conversation_id": "conv-shell",
+ "hook_event_name": "afterShellExecution",
+ "command": "go test ./...",
+ "output": "ok",
+ "duration": float64(1234),
+ "cwd": "/repo",
+ })
+ if len(out) != 0 {
+ t.Fatalf("post-tool response = %#v, want empty response", out)
+ }
+
+ event := lastEndpointEvent(t, logPath)
+ if action := event["event"].(map[string]interface{})["action"]; action != "command.executed" {
+ t.Fatalf("event.action = %q, want command.executed", action)
+ }
+ command := event["command"].(map[string]interface{})
+ if command["command"] != "go test ./..." || command["output"] != "ok" {
+ t.Fatalf("command = %#v, want command and output", command)
+ }
+}
+
+func TestRunPostToolEmitsCursorPostToolFailure(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "cursor"
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ out := runHookWithInput(t, runPostTool, map[string]interface{}{
+ "conversation_id": "conv-failure",
+ "hook_event_name": "postToolUseFailure",
+ "tool_name": "Shell",
+ "tool_input": map[string]interface{}{
+ "command": "npm test",
+ },
+ "error_message": "Command timed out",
+ "failure_type": "timeout",
+ "cwd": "/repo",
+ })
+ if len(out) != 0 {
+ t.Fatalf("post-tool response = %#v, want empty response", out)
+ }
+
+ event := lastEndpointEvent(t, logPath)
+ if action := event["event"].(map[string]interface{})["action"]; action != "tool.failed" {
+ t.Fatalf("event.action = %q, want tool.failed", action)
+ }
+ if severity := event["severity"]; severity != "high" {
+ t.Fatalf("severity = %q, want high", severity)
+ }
+ tool := event["tool"].(map[string]interface{})
+ if tool["name"] != "Shell" || tool["failure_type"] != "timeout" {
+ t.Fatalf("tool = %#v, want Shell timeout", tool)
+ }
+}
+
func TestRunPostToolEmitsAntigravityFileModifiedEvent(t *testing.T) {
setupHookConfigDirs(t)
platformFlag = "antigravity"
diff --git a/cli/beacon-hooks/cmd/pre_tool.go b/cli/beacon-hooks/cmd/pre_tool.go
index c9963ca0..1fb91ec3 100644
--- a/cli/beacon-hooks/cmd/pre_tool.go
+++ b/cli/beacon-hooks/cmd/pre_tool.go
@@ -44,7 +44,9 @@ func runPreTool(cmd *cobra.Command, args []string) {
}
logger.Debug("Pre-tool observed")
- if platformFlag == "antigravity" {
+ if platformFlag == "cursor" && emitCursorPreHook(logger, input, sessionID) {
+ maybeUploadCursorCloudTelemetry(logger)
+ } else if platformFlag == "antigravity" {
emitAntigravityPromptFromTranscript(logger, input, sessionID)
emitPreToolObserved(logger, input, sessionID)
} else if platformFlag == "claude" || isDevinLikePlatform(platformFlag) || platformFlag == "grok" || platformFlag == "hermes" || platformFlag == "vscode" {
@@ -55,6 +57,36 @@ func runPreTool(cmd *cobra.Command, args []string) {
outputJSON(preToolResponse())
}
+func emitCursorPreHook(logger *logging.Logger, input map[string]interface{}, sessionID string) bool {
+ switch getFirstStr(input, "hook_event_name", "hookEventName") {
+ case "beforeShellExecution":
+ fields := sessionFields(sessionID, input)
+ command := getFirstStr(input, "command")
+ fields["command"] = map[string]interface{}{"command": command}
+ fields["approval"] = map[string]interface{}{
+ "required": true,
+ "decision": "allow",
+ "reason": "Shell execution observed",
+ }
+ emitHookEvent(logger, "approval.allowed", "approval", "info", "Shell execution observed", input, fields)
+ return true
+ case "beforeReadFile":
+ fields := sessionFields(sessionID, input)
+ if filePath := getFirstStr(input, "file_path", "filePath", "path"); filePath != "" {
+ fields["file"] = map[string]interface{}{
+ "path": filePath,
+ "operation": "read",
+ "language": strings.TrimPrefix(filepath.Ext(filePath), "."),
+ }
+ }
+ emitHookEvent(logger, "file.read", "file", "info", "File read observed", input, fields)
+ return true
+ default:
+ emitPreToolDecision(logger, input, sessionID, "approval.allowed", "allow", "Pre-tool observed")
+ return true
+ }
+}
+
func emitPreToolDecision(logger *logging.Logger, input map[string]interface{}, sessionID, action, decision, reason string) {
toolName := getFirstStr(input, "tool_name", "toolName")
toolInput := resolveToolInput(input)
diff --git a/cli/beacon-hooks/cmd/pre_tool_test.go b/cli/beacon-hooks/cmd/pre_tool_test.go
index 9d69e2a1..312a6cd4 100644
--- a/cli/beacon-hooks/cmd/pre_tool_test.go
+++ b/cli/beacon-hooks/cmd/pre_tool_test.go
@@ -55,6 +55,68 @@ func TestRunPromptSubmitUsesCursorResponse(t *testing.T) {
}
}
+func TestRunPreToolEmitsCursorBeforeShellExecution(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "cursor"
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ t.Setenv("BEACON_ORIGIN", "cloud")
+ t.Setenv("BEACON_RUN_PROVIDER", "cursor_cloud")
+
+ out := runHookWithInput(t, runPreTool, map[string]interface{}{
+ "conversation_id": "conv-shell",
+ "hook_event_name": "beforeShellExecution",
+ "command": "npm test",
+ "cwd": "/repo",
+ "workspace_roots": []interface{}{"/repo"},
+ "cursor_version": "1.7.2",
+ "generation_id": "gen-1",
+ "model": "gpt-5.5",
+ "BEACON_SENTINEL": "ignored",
+ })
+ if out["permission"] != "allow" {
+ t.Fatalf("beforeShellExecution response = %#v, want permission allow", out)
+ }
+
+ event := lastEndpointEvent(t, logPath)
+ if action := event["event"].(map[string]interface{})["action"]; action != "approval.allowed" {
+ t.Fatalf("event.action = %q, want approval.allowed", action)
+ }
+ if command := event["command"].(map[string]interface{})["command"]; command != "npm test" {
+ t.Fatalf("command = %q, want npm test", command)
+ }
+ if provider := event["run"].(map[string]interface{})["provider"]; provider != "cursor_cloud" {
+ t.Fatalf("run.provider = %q, want cursor_cloud", provider)
+ }
+}
+
+func TestRunPreToolEmitsCursorBeforeReadFile(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "cursor"
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+
+ out := runHookWithInput(t, runPreTool, map[string]interface{}{
+ "conversation_id": "conv-read",
+ "hook_event_name": "beforeReadFile",
+ "file_path": "/repo/main.go",
+ "content": "token=cursor-secret",
+ "cwd": "/repo",
+ })
+ if out["permission"] != "allow" {
+ t.Fatalf("beforeReadFile response = %#v, want permission allow", out)
+ }
+
+ event := lastEndpointEvent(t, logPath)
+ if action := event["event"].(map[string]interface{})["action"]; action != "file.read" {
+ t.Fatalf("event.action = %q, want file.read", action)
+ }
+ file := event["file"].(map[string]interface{})
+ if file["path"] != "/repo/main.go" || file["operation"] != "read" {
+ t.Fatalf("file = %#v, want /repo/main.go read", file)
+ }
+}
+
func TestVSCodeHooksEmitLowNoiseTelemetry(t *testing.T) {
setupHookConfigDirs(t)
platformFlag = "vscode"
@@ -116,6 +178,63 @@ func TestRunSubagentLifecycleEmitsVSCodeEvents(t *testing.T) {
}
}
+func TestRunSubagentLifecycleEmitsCursorCloudFields(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "cursor"
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ t.Setenv("BEACON_ORIGIN", "cloud")
+ t.Setenv("BEACON_RUN_PROVIDER", "cursor_cloud")
+
+ runHookWithInput(t, func(cmd *cobra.Command, args []string) {
+ runSubagentLifecycle("subagent.started", "Subagent started")
+ }, map[string]interface{}{
+ "hook_event_name": "subagentStart",
+ "parent_conversation_id": "conv-parent",
+ "subagent_id": "subagent-1",
+ "subagent_type": "generalPurpose",
+ "subagent_model": "gpt-5.5",
+ "tool_call_id": "tool-1",
+ "git_branch": "feature/cursor-cloud",
+ "cwd": "/repo",
+ })
+
+ event := lastEndpointEvent(t, logPath)
+ if action := event["event"].(map[string]interface{})["action"]; action != "subagent.started" {
+ t.Fatalf("event.action = %q, want subagent.started", action)
+ }
+ if sessionID := event["session"].(map[string]interface{})["id"]; sessionID != "conv-parent" {
+ t.Fatalf("session.id = %q, want conv-parent", sessionID)
+ }
+ raw := event["raw"].(map[string]interface{})["subagent"].(map[string]interface{})
+ if raw["id"] != "subagent-1" || raw["type"] != "generalPurpose" || raw["tool_call_id"] != "tool-1" {
+ t.Fatalf("raw.subagent = %#v, want Cursor subagent fields", raw)
+ }
+}
+
+func TestRunCursorEventEmitsPreCompact(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "cursor"
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ t.Setenv("BEACON_ORIGIN", "cloud")
+ t.Setenv("BEACON_RUN_PROVIDER", "cursor_cloud")
+
+ out := runHookWithInput(t, runCursorEvent, map[string]interface{}{
+ "conversation_id": "conv-compact",
+ "hook_event_name": "preCompact",
+ "cwd": "/repo",
+ })
+ if len(out) != 0 {
+ t.Fatalf("cursor-event response = %#v, want empty response", out)
+ }
+
+ event := lastEndpointEvent(t, logPath)
+ if action := event["event"].(map[string]interface{})["action"]; action != "session.compacting" {
+ t.Fatalf("event.action = %q, want session.compacting", action)
+ }
+}
+
func TestRunPromptSubmitEmitsFactoryPromptEvent(t *testing.T) {
setupHookConfigDirs(t)
platformFlag = "factory"
diff --git a/cli/beacon-hooks/cmd/subagent.go b/cli/beacon-hooks/cmd/subagent.go
index 8994fe1a..d7d50e24 100644
--- a/cli/beacon-hooks/cmd/subagent.go
+++ b/cli/beacon-hooks/cmd/subagent.go
@@ -42,8 +42,21 @@ func runSubagentLifecycle(action, message string) {
}
fields := sessionFields(sessionID, input)
subagent := map[string]interface{}{
- "id": getFirstStr(input, "agent_id", "agentId"),
- "type": getFirstStr(input, "agent_type", "agentType"),
+ "id": getFirstStr(input, "subagent_id", "agent_id", "agentId"),
+ "type": getFirstStr(input, "subagent_type", "agent_type", "agentType"),
+ }
+ if platformFlag == "cursor" {
+ subagent = mergeNested(subagent, map[string]interface{}{
+ "status": getFirstStr(input, "status"),
+ "summary": getFirstStr(input, "summary"),
+ "description": getFirstStr(input, "description"),
+ "parent_conversation": getFirstStr(input, "parent_conversation_id"),
+ "tool_call_id": getFirstStr(input, "tool_call_id"),
+ "model": getFirstStr(input, "subagent_model"),
+ "duration_ms": input["duration_ms"],
+ "message_count": input["message_count"],
+ "tool_call_count": input["tool_call_count"],
+ })
}
if platformFlag == "hermes" {
if extra := hermesExtra(input); extra != nil {
@@ -56,13 +69,19 @@ func runSubagentLifecycle(action, message string) {
}
}
fields["raw"] = mergeNested(fields["raw"], map[string]interface{}{"subagent": map[string]interface{}{
- "id": subagent["id"],
- "type": subagent["type"],
- "role": subagent["role"],
- "status": subagent["status"],
- "summary": subagent["summary"],
- "duration_ms": subagent["duration_ms"],
+ "id": subagent["id"],
+ "type": subagent["type"],
+ "role": subagent["role"],
+ "status": subagent["status"],
+ "summary": subagent["summary"],
+ "description": subagent["description"],
+ "parent_conversation": subagent["parent_conversation"],
+ "tool_call_id": subagent["tool_call_id"],
+ "duration_ms": subagent["duration_ms"],
+ "message_count": subagent["message_count"],
+ "tool_call_count": subagent["tool_call_count"],
}})
emitHookEvent(logger, action, "session", "info", message, input, fields)
+ maybeUploadCursorCloudTelemetry(logger)
outputJSON(emptyResponse)
}
diff --git a/cli/beacon-hooks/internal/cloudshuttle/shuttle_test.go b/cli/beacon-hooks/internal/cloudshuttle/shuttle_test.go
index 909a8269..b911c2ad 100644
--- a/cli/beacon-hooks/internal/cloudshuttle/shuttle_test.go
+++ b/cli/beacon-hooks/internal/cloudshuttle/shuttle_test.go
@@ -31,6 +31,19 @@ func TestObjectNamePartitionsByProviderUserRepoAndRun(t *testing.T) {
}
}
+func TestObjectNameUsesCursorCloudProvider(t *testing.T) {
+ got := ObjectName(Config{
+ Prefix: "agent-traces",
+ Provider: "cursor_cloud",
+ UserID: "user-1",
+ RunID: "manual-123",
+ })
+ want := "agent-traces/provider=cursor_cloud/user_id=user-1/run_id=manual-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 {
diff --git a/cli/beacon/README.md b/cli/beacon/README.md
index 96f28e3e..fddf3872 100644
--- a/cli/beacon/README.md
+++ b/cli/beacon/README.md
@@ -38,7 +38,7 @@ configured.
## Cloud Agent Telemetry
Use `beacon cloud` helpers to configure provider-managed cloud agent sandboxes.
-The first supported path is Claude Code on the web forwarding Beacon JSONL to
+Claude Code on the web and Cursor cloud agents can forward Beacon JSONL to
customer-managed GCS:
```bash
@@ -53,32 +53,39 @@ customer-managed GCS:
Copy the printed `BEACON_CLOUD_GCS_BUCKET`,
`BEACON_CLOUD_GCS_PREFIX`, and `BEACON_CLOUD_GCS_CREDENTIALS_B64`
-values into the Claude Code web environment. Also set:
+values into the cloud agent environment. Also set:
```bash
BEACON_ORIGIN=cloud
-BEACON_RUN_PROVIDER=claude_code_web
+BEACON_RUN_PROVIDER=claude_code_web # or cursor_cloud
BEACON_RUN_EPHEMERAL=true
BEACON_CLOUD_USER_ID_HASH=<stable-user-or-test-id>
```
Then generate the setup script for a Beacon release and paste it into the
-Claude Code web environment setup field:
+provider's cloud setup field:
```bash
./beacon cloud claude-web print-setup --version vX.Y.Z
+./beacon cloud cursor print-setup --version vX.Y.Z
```
-The setup script installs `beacon-hooks` into the cloud sandbox, writes
-`.claude/settings.local.json` inside the sandbox clone, and uploads one
-browser-viewable per-session `/tmp/beacon/runtime.jsonl` snapshot to GCS at:
+The setup script installs `beacon-hooks` into the cloud sandbox and uploads a
+browser-viewable `/tmp/beacon/runtime.jsonl` snapshot to GCS. Claude web writes
+`.claude/settings.local.json` inside the sandbox clone. Cursor cloud merges
+Beacon commands into project-level `.cursor/hooks.json` because Cursor cloud
+only runs repository project hooks.
```text
<prefix>/provider=claude_code_web/user_id=<id>/run_id=<claude-session-id>/runtime.jsonl
+<prefix>/provider=cursor_cloud/user_id=<id>/run_id=<generated-or-explicit-run-id>/runtime.jsonl
```
-Claude web network access must allow `oauth2.googleapis.com` and
-`storage.googleapis.com`. If you are testing unreleased Beacon changes, clone
+Cloud network access must allow `oauth2.googleapis.com` and
+`storage.googleapis.com`. Cursor cloud currently supports command hooks for tool
+activity, shell execution, file reads and edits, subagents, and compaction
+events; it does not currently run session start, session end, prompt submit, or
+stop hooks in cloud agents. If you are testing unreleased Beacon changes, clone
and build the feature branch in the setup script instead of using
`print-setup --version`.
diff --git a/cli/beacon/cmd/cloud.go b/cli/beacon/cmd/cloud.go
index e35401dd..481afb0a 100644
--- a/cli/beacon/cmd/cloud.go
+++ b/cli/beacon/cmd/cloud.go
@@ -10,6 +10,7 @@ import (
"strings"
"time"
+ endpointhooks "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks"
"github.com/spf13/cobra"
)
@@ -19,6 +20,7 @@ var cloudOpts struct {
version string
project string
bucket string
+ hooksJSONPath string
location string
prefix string
serviceAccount string
@@ -37,6 +39,11 @@ var cloudClaudeWebCmd = &cobra.Command{
Short: "Generate Claude Code on the web telemetry setup",
}
+var cloudCursorCmd = &cobra.Command{
+ Use: "cursor",
+ Short: "Generate Cursor cloud agent telemetry setup",
+}
+
var cloudClaudeWebPrintHooksCmd = &cobra.Command{
Use: "print-hooks",
Short: "Print project-level Claude hook settings for a cloud sandbox",
@@ -66,6 +73,61 @@ var cloudClaudeWebPrintSetupCmd = &cobra.Command{
},
}
+var cloudCursorPrintHooksCmd = &cobra.Command{
+ Use: "print-hooks",
+ Short: "Print project-level Cursor 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")
+ }
+ rendered, err := endpointhooks.RenderCursorCloudHooks(endpointhooks.CursorCloudOptions{
+ BinaryPath: cloudOpts.binaryPath,
+ LogPath: defaultCloudLogPath(cloudOpts.logPath),
+ })
+ if err != nil {
+ return err
+ }
+ fmt.Print(rendered)
+ return nil
+ },
+}
+
+var cloudCursorInstallHooksCmd = &cobra.Command{
+ Use: "install-hooks",
+ Short: "Merge Beacon hooks into project-level Cursor cloud hook settings",
+ SilenceUsage: true,
+ RunE: func(cmd *cobra.Command, args []string) error {
+ if strings.TrimSpace(cloudOpts.binaryPath) == "" {
+ return fmt.Errorf("--binary-path is required")
+ }
+ path := strings.TrimSpace(cloudOpts.hooksJSONPath)
+ if path == "" {
+ path = filepath.Join(".cursor", "hooks.json")
+ }
+ if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+ return err
+ }
+ return endpointhooks.InstallCursorCloudHooksJSON(path, endpointhooks.CursorCloudOptions{
+ BinaryPath: cloudOpts.binaryPath,
+ LogPath: defaultCloudLogPath(cloudOpts.logPath),
+ })
+ },
+}
+
+var cloudCursorPrintSetupCmd = &cobra.Command{
+ Use: "print-setup",
+ Short: "Print a Cursor cloud agent 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(renderCursorCloudSetup(cloudOpts.version))
+ return nil
+ },
+}
+
var cloudGCSCmd = &cobra.Command{
Use: "gcs",
Short: "Configure GCS forwarding for cloud agent telemetry",
@@ -81,14 +143,24 @@ var cloudGCSSetupCmd = &cobra.Command{
func init() {
rootCmd.AddCommand(cloudCmd)
cloudCmd.AddCommand(cloudClaudeWebCmd)
+ cloudCmd.AddCommand(cloudCursorCmd)
cloudCmd.AddCommand(cloudGCSCmd)
cloudClaudeWebCmd.AddCommand(cloudClaudeWebPrintHooksCmd)
cloudClaudeWebCmd.AddCommand(cloudClaudeWebPrintSetupCmd)
+ cloudCursorCmd.AddCommand(cloudCursorPrintHooksCmd)
+ cloudCursorCmd.AddCommand(cloudCursorInstallHooksCmd)
+ cloudCursorCmd.AddCommand(cloudCursorPrintSetupCmd)
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")
+ cloudCursorPrintHooksCmd.Flags().StringVar(&cloudOpts.binaryPath, "binary-path", "", "Path to beacon-hooks inside the cloud sandbox")
+ cloudCursorPrintHooksCmd.Flags().StringVar(&cloudOpts.logPath, "log-path", "/tmp/beacon/runtime.jsonl", "Cloud sandbox runtime JSONL path")
+ cloudCursorInstallHooksCmd.Flags().StringVar(&cloudOpts.binaryPath, "binary-path", "", "Path to beacon-hooks inside the cloud sandbox")
+ cloudCursorInstallHooksCmd.Flags().StringVar(&cloudOpts.logPath, "log-path", "/tmp/beacon/runtime.jsonl", "Cloud sandbox runtime JSONL path")
+ cloudCursorInstallHooksCmd.Flags().StringVar(&cloudOpts.hooksJSONPath, "hooks-json", filepath.Join(".cursor", "hooks.json"), "Path to the project-level Cursor hooks.json")
+ cloudCursorPrintSetupCmd.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")
@@ -100,6 +172,13 @@ func init() {
cloudGCSSetupCmd.Flags().BoolVar(&cloudOpts.printEnv, "print-env", false, "Print Claude web environment variables after setup")
}
+func defaultCloudLogPath(path string) string {
+ if strings.TrimSpace(path) == "" {
+ return "/tmp/beacon/runtime.jsonl"
+ }
+ return path
+}
+
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{}{
@@ -182,6 +261,47 @@ echo "Beacon hooks installed at $REPO_ROOT/.claude/settings.local.json"
`, version)
}
+func renderCursorCloudSetup(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
+
+REPO_ROOT="${BEACON_CLOUD_REPO_DIR:-${CURSOR_PROJECT_DIR:-}}"
+if [ -z "$REPO_ROOT" ]; then
+ REPO_ROOT="$(pwd)"
+fi
+if [ -z "$REPO_ROOT" ] || [ ! -d "$REPO_ROOT" ]; then
+ echo "Could not find Cursor cloud repo root" >&2
+ exit 1
+fi
+
+mkdir -p "$REPO_ROOT/.cursor"
+cat >> "$REPO_ROOT/.git/info/exclude" <<'EOF'
+.cursor/hooks.json
+EOF
+cd "$REPO_ROOT"
+/tmp/beacon/bin/beacon cloud cursor install-hooks \
+ --binary-path /tmp/beacon/bin/beacon-hooks \
+ --log-path /tmp/beacon/runtime.jsonl \
+ --hooks-json "$REPO_ROOT/.cursor/hooks.json"
+
+echo "Beacon hooks installed at $REPO_ROOT/.cursor/hooks.json"
+`, version)
+}
+
func runCloudGCSSetup(cmd *cobra.Command, args []string) error {
if cloudOpts.project == "" {
return fmt.Errorf("--project is required")
diff --git a/cli/beacon/cmd/cloud_test.go b/cli/beacon/cmd/cloud_test.go
index 377ba0da..54fa124e 100644
--- a/cli/beacon/cmd/cloud_test.go
+++ b/cli/beacon/cmd/cloud_test.go
@@ -3,12 +3,17 @@ package cmd
import (
"strings"
"testing"
+
+ endpointhooks "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks"
)
func TestCloudCommandsRegistered(t *testing.T) {
for _, path := range [][]string{
{"cloud", "claude-web", "print-hooks"},
{"cloud", "claude-web", "print-setup"},
+ {"cloud", "cursor", "print-hooks"},
+ {"cloud", "cursor", "install-hooks"},
+ {"cloud", "cursor", "print-setup"},
{"cloud", "gcs", "setup"},
} {
cmd, _, err := rootCmd.Find(path)
@@ -21,6 +26,59 @@ func TestCloudCommandsRegistered(t *testing.T) {
}
}
+func TestRenderCursorCloudHooks(t *testing.T) {
+ got, err := endpointhooks.RenderCursorCloudHooks(endpointhooks.CursorCloudOptions{
+ BinaryPath: "/tmp/beacon/bin/beacon-hooks",
+ LogPath: "/tmp/beacon/runtime.jsonl",
+ })
+ if err != nil {
+ t.Fatalf("render cursor cloud hooks: %v", err)
+ }
+ for _, want := range []string{
+ `"version": 1`,
+ `"preToolUse"`,
+ `"postToolUse"`,
+ `"postToolUseFailure"`,
+ `"beforeShellExecution"`,
+ `"afterShellExecution"`,
+ `"beforeReadFile"`,
+ `"afterFileEdit"`,
+ `"subagentStart"`,
+ `"subagentStop"`,
+ `"preCompact"`,
+ `BEACON_ORIGIN=cloud`,
+ `BEACON_RUN_PROVIDER=cursor_cloud`,
+ `'/tmp/beacon/bin/beacon-hooks' --platform cursor`,
+ } {
+ if !strings.Contains(got, want) {
+ t.Fatalf("rendered hooks missing %q:\n%s", want, got)
+ }
+ }
+ for _, unsupported := range []string{`"sessionStart"`, `"sessionEnd"`, `"beforeSubmitPrompt"`, `"stop"`} {
+ if strings.Contains(got, unsupported) {
+ t.Fatalf("rendered cursor cloud hooks should not contain %q:\n%s", unsupported, got)
+ }
+ }
+}
+
+func TestRenderCursorCloudSetupInstallsHooks(t *testing.T) {
+ got := renderCursorCloudSetup("v0.0.50")
+ for _, want := range []string{
+ `BEACON_VERSION="v0.0.50"`,
+ `REPO_ROOT="${BEACON_CLOUD_REPO_DIR:-${CURSOR_PROJECT_DIR:-}}"`,
+ `.cursor/hooks.json`,
+ `beacon cloud cursor install-hooks`,
+ `--hooks-json "$REPO_ROOT/.cursor/hooks.json"`,
+ } {
+ if !strings.Contains(got, want) {
+ t.Fatalf("rendered setup missing %q:\n%s", want, got)
+ }
+ }
+ if strings.Contains(got, `> "$REPO_ROOT/.cursor/hooks.json"`) {
+ t.Fatalf("cursor setup should merge hooks instead of overwriting hooks.json:\n%s", got)
+ }
+}
+
func TestRenderClaudeWebHooks(t *testing.T) {
got := renderClaudeWebHooks("/tmp/beacon/bin/beacon-hooks", "/tmp/beacon/runtime.jsonl")
for _, want := range []string{
diff --git a/cli/beacon/internal/endpoint/hooks/cursor.go b/cli/beacon/internal/endpoint/hooks/cursor.go
index dc33ac20..eed7767e 100644
--- a/cli/beacon/internal/endpoint/hooks/cursor.go
+++ b/cli/beacon/internal/endpoint/hooks/cursor.go
@@ -31,6 +31,11 @@ type CursorOptions struct {
UserMode bool
}
+type CursorCloudOptions struct {
+ BinaryPath string
+ LogPath string
+}
+
type CursorStatus struct {
Installed bool `json:"installed"`
BinaryPath string `json:"binary_path,omitempty"`
@@ -105,6 +110,76 @@ func installCursorHooksJSON(path, binaryPath, logPath, configPath string) error
return os.WriteFile(path, data, 0644)
}
+func InstallCursorCloudHooksJSON(path string, opts CursorCloudOptions) error {
+ hooksJSON, err := readHooksJSON(path)
+ if err != nil {
+ return err
+ }
+ for hookName, refs := range CursorCloudHookRefs(opts) {
+ merged := hooksJSON.Hooks[hookName]
+ for _, ref := range refs {
+ merged = mergeEndpointHook(merged, ref)
+ }
+ hooksJSON.Hooks[hookName] = merged
+ }
+ data, err := json.MarshalIndent(hooksJSON, "", " ")
+ if err != nil {
+ return err
+ }
+ return os.WriteFile(path, data, 0644)
+}
+
+func RenderCursorCloudHooks(opts CursorCloudOptions) (string, error) {
+ hooksJSON := HooksJSON{
+ Version: 1,
+ Hooks: CursorCloudHookRefs(opts),
+ }
+ data, err := json.MarshalIndent(hooksJSON, "", " ")
+ if err != nil {
+ return "", err
+ }
+ return string(data) + "\n", nil
+}
+
+func CursorCloudHookRefs(opts CursorCloudOptions) map[string][]HookRef {
+ if opts.LogPath == "" {
+ opts.LogPath = "/tmp/beacon/runtime.jsonl"
+ }
+ prefix := cursorCloudCommandPrefix(opts.BinaryPath, opts.LogPath)
+ return map[string][]HookRef{
+ "preToolUse": {{Command: prefix + " pre-tool"}},
+ "postToolUse": {{Command: prefix + " post-tool"}},
+ "postToolUseFailure": {{Command: prefix + " post-tool"}},
+ "beforeShellExecution": {
+ {Command: prefix + " pre-tool"},
+ },
+ "afterShellExecution": {
+ {Command: prefix + " post-tool"},
+ },
+ "beforeReadFile": {
+ {Command: prefix + " pre-tool"},
+ },
+ "afterFileEdit": {{Command: prefix + " post-tool"}},
+ "subagentStart": {
+ {Command: prefix + " subagent-start"},
+ },
+ "subagentStop": {
+ {Command: prefix + " subagent-stop"},
+ },
+ "preCompact": {
+ {Command: prefix + " cursor-event"},
+ },
+ }
+}
+
+func cursorCloudCommandPrefix(binaryPath, logPath string) string {
+ return fmt.Sprintf(
+ "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=%s %s --platform cursor",
+ shellQuote(logPath),
+ shellQuote(binaryPath),
+ )
+}
+
func readHooksJSON(path string) (HooksJSON, error) {
var hooksJSON HooksJSON
data, err := os.ReadFile(path)
diff --git a/cli/beacon/internal/endpoint/hooks/cursor_test.go b/cli/beacon/internal/endpoint/hooks/cursor_test.go
index 879fe834..caea8971 100644
--- a/cli/beacon/internal/endpoint/hooks/cursor_test.go
+++ b/cli/beacon/internal/endpoint/hooks/cursor_test.go
@@ -153,6 +153,67 @@ func TestInstallCursorHooksJSONDoesNotReplaceUserCommandWithBeaconEnvOnly(t *tes
}
}
+func TestInstallCursorCloudHooksJSONPreservesNonBeaconHooks(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "hooks.json")
+ existing := `{"version":1,"hooks":{"preToolUse":[{"command":"echo keep"}],"sessionStart":[{"command":"echo local-only"}]}}`
+ if err := os.WriteFile(path, []byte(existing), 0644); err != nil {
+ t.Fatal(err)
+ }
+
+ if err := InstallCursorCloudHooksJSON(path, CursorCloudOptions{
+ BinaryPath: "/tmp/beacon-hooks",
+ LogPath: "/tmp/runtime.jsonl",
+ }); err != nil {
+ t.Fatalf("InstallCursorCloudHooksJSON returned error: %v", err)
+ }
+ data, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("read hooks.json: %v", err)
+ }
+ text := string(data)
+ for _, want := range []string{
+ "echo keep",
+ "echo local-only",
+ "BEACON_ORIGIN=cloud",
+ "BEACON_RUN_PROVIDER=cursor_cloud",
+ "beforeShellExecution",
+ "preCompact",
+ } {
+ if !strings.Contains(text, want) {
+ t.Fatalf("merged cursor cloud hooks missing %q:\n%s", want, text)
+ }
+ }
+ if strings.Contains(text, `"sessionEnd"`) || strings.Contains(text, `"beforeSubmitPrompt"`) {
+ t.Fatalf("cursor cloud install should not add unsupported cloud hooks:\n%s", text)
+ }
+}
+
+func TestInstallCursorCloudHooksJSONReplacesExistingBeaconHook(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "hooks.json")
+ existing := `{"version":1,"hooks":{"preToolUse":[{"command":"BEACON_ENDPOINT_MODE=1 old-beacon-hooks --platform cursor pre-tool"},{"command":"echo keep"}]}}`
+ if err := os.WriteFile(path, []byte(existing), 0644); err != nil {
+ t.Fatal(err)
+ }
+
+ if err := InstallCursorCloudHooksJSON(path, CursorCloudOptions{
+ BinaryPath: "/tmp/new-beacon-hooks",
+ LogPath: "/tmp/runtime.jsonl",
+ }); err != nil {
+ t.Fatalf("InstallCursorCloudHooksJSON returned error: %v", err)
+ }
+ data, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("read hooks.json: %v", err)
+ }
+ text := string(data)
+ if strings.Contains(text, "old-beacon-hooks") {
+ t.Fatalf("old Beacon hook was not replaced:\n%s", text)
+ }
+ if !strings.Contains(text, "echo keep") || !strings.Contains(text, "/tmp/new-beacon-hooks") {
+ t.Fatalf("merged hook config missing kept or new hook:\n%s", text)
+ }
+}
+
func TestInstallCursorWithUnknownLevelFailsBeforeWritingTarget(t *testing.T) {
home := t.TempDir()
t.Setenv("HOME", home)