Skip to content

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

36.7 KB
Raw Blame
package logging

import (
	"encoding/json"
	"fmt"
	"io"
	"os"
	osuser "os/user"
	"path/filepath"
	"runtime"
	"strconv"
	"strings"
	"sync"
	"testing"
	"time"

	"github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/config"
	"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
	"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/activesession"
	"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/filelock"
	"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/localingest"
	"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/shareauto"
)

// endpointSequence numbers the endpoint events emitted by this hook process, in the order
// they are written.
var endpointSequence asymptoteobserve.Sequencer

const (
	defaultEndpointRotateBytes    = 10 * 1024 * 1024
	defaultEndpointRotateArchives = asymptoteobserve.DefaultRuntimeLogRotateArchives
	// endpointRuntimeFileMode is the shared (system-mode) log's mode. A log inside the current
	// user's home is private instead; asymptoteobserve.RuntimeLogModes decides, identically in all
	// three writers.
	endpointRuntimeFileMode = asymptoteobserve.SharedRuntimeLogFileMode
)

// endpointEventsSuppressed stops this process writing endpoint events. A hook sets it when another
// hook of Beacon's records the same event, as when Cursor runs Beacon's Claude Code hooks next to
// its own.
var endpointEventsSuppressed bool

// SuppressEndpointEvents turns endpoint event writes off (true) or back on (false) for the rest of
// this process.
func SuppressEndpointEvents(suppress bool) {
	endpointEventsSuppressed = suppress
}

// Logger provides structured JSON logging for hook events
type Logger struct {
	hookName  string
	logFile   string
	sessionID string
	platform  string
}

// NewLoggerForPlatform creates a logger for a specific hook and platform
func NewLoggerForPlatform(hookName, platform string) *Logger {
	config.EnsureStateDir(platform)
	return &Logger{hookName: hookName, logFile: config.GetLogFile(platform), platform: platform}
}

// NewSessionLogger creates a logger that writes to a per-session log file.
// Log file path: ~/.beacon/{platform}/logs/{session_id}.log
func NewSessionLogger(hookName, platform, sessionID string) *Logger {
	config.EnsureSessionLogDir(platform)
	return &Logger{
		hookName:  hookName,
		logFile:   config.GetSessionLogFile(platform, sessionID),
		sessionID: sessionID,
		platform:  platform,
	}
}

func (l *Logger) formatEntry(level, message string, fields ...interface{}) map[string]interface{} {
	entry := map[string]interface{}{
		"timestamp": time.Now().UTC().Format(time.RFC3339),
		"hook":      l.hookName,
		"level":     level,
		"message":   message,
	}

	if l.sessionID != "" {
		entry["session_id"] = l.sessionID
	}

	// Add additional fields
	for i := 0; i < len(fields)-1; i += 2 {
		if key, ok := fields[i].(string); ok {
			entry[key] = fields[i+1]
		}
	}

	return entry
}

func (l *Logger) write(entry map[string]interface{}) {
	data, err := json.Marshal(entry)
	if err != nil {
		return
	}

	f, err := os.OpenFile(l.logFile, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
	if err != nil {
		return
	}
	defer func() {
		if cerr := f.Close(); cerr != nil {
			fmt.Fprintf(os.Stderr, "logging: failed to close log file %s: %v\n", l.logFile, cerr)
		}
	}()

	if _, err := f.Write(data); err != nil {
		fmt.Fprintf(os.Stderr, "logging: failed to write log entry to %s: %v\n", l.logFile, err)
		return
	}
	if _, err := f.WriteString("\n"); err != nil {
		fmt.Fprintf(os.Stderr, "logging: failed to write newline to %s: %v\n", l.logFile, err)
		return
	}
}

// EndpointEvent writes an event whose action the runtime named for us, which is the normal case
// on this path: a hook or plugin fires for a specific lifecycle event and the action follows from
// which one. Callers that instead derive an action from an adjacent observation must use
// EndpointEventWithFidelity and say so.
func (l *Logger) EndpointEvent(action, category, severity, message string, fields map[string]interface{}) error {
	return l.EndpointEventWithFidelity(action, category, severity, message, asymptoteobserve.FidelityObserved, fields)
}

// EndpointEventWithFidelity is EndpointEvent with an explicit event.fidelity. It exists for the
// handful of hook paths that report an action the payload did not contain -- synthesizing an
// approval from a pre-tool notification, for instance -- so those events are distinguishable from
// the ones a runtime actually reported.
func (l *Logger) EndpointEventWithFidelity(action, category, severity, message, fidelity string, fields map[string]interface{}) error {
	if endpointEventsSuppressed {
		return nil
	}
	path := endpointLogPath()
	if path == "" {
		return nil
	}
	if severity == "" {
		severity = "info"
	}
	event := l.baseEndpointEvent(action, category, severity, message, fidelity)
	for key, value := range fields {
		if value == nil {
			continue
		}
		event[key] = value
	}
	normalizeEventModel(event)
	attachDerivedTrace(event)
	if err := writeEndpointJSON(path, event); err != nil {
		// A hook inside a sandbox that confines writes to the session workspace cannot reach the
		// runtime log (DeepSeek Harness first, #605; container and operator sandboxes since, #1284)
		// but can write the workspace. Staging the event there keeps capture live; a sweep, `beacon
		// endpoint spool drain`, or this session's next hook that can reach the log drains it. A
		// staged event is not reported as lost; the first one a session stages prints one note
		// saying where it waits (stageInWorkspaceSpool). When staging fails too -- read-only mode,
		// no workspace, unsafe ids, a full spool, a Beacon-only action -- the NOT-recorded
		// explanation below fires unchanged, which is the honest report for an event nothing
		// captured.
		if l.stageInWorkspaceSpool(event, path) {
			return nil
		}
		fmt.Fprintf(os.Stderr, "logging: failed to write endpoint event to %s: %v\n", path, err)
		reportEndpointWriteFailure(os.Stderr, l.platform, path, err)
		return err
	}
	l.drainOwnWorkspaceSpool(path, event)
	recordActiveSession(event)
	l.requestShareOnce(event)
	return nil
}

// ShareSettingsPath locates the user's share settings. It is never taken from the environment,
// which a repository can supply; tests replace it.
var ShareSettingsPath = shareauto.HookPath

// requestShareOnce writes one session.share_requested event for the event's session when the person
// turned auto-share on for its working directory (`beacon share auto enable`). It is the first event
// of the session the hooks see -- SessionStart where the runtime has one -- and never more than one
// per session, deduplicated under a lock in the active-session record.
//
// The event is only written to the local runtime log. Beacon Cloud forwarding ships it like any
// other line, and beacon.sh publishes the session when it receives it; without forwarding it is an
// inert record. Nothing here touches the network. It is event.fidelity=inferred because Beacon
// originated it: no runtime reported a share request.
func (l *Logger) requestShareOnce(event map[string]interface{}) {
	info, _ := event["event"].(map[string]interface{})
	if action, _ := info["action"].(string); action == asymptoteobserve.ActionShareRequested {
		return
	}
	session, _ := event["session"].(map[string]interface{})
	harness, _ := event["harness"].(map[string]interface{})
	if session == nil || harness == nil {
		return
	}
	id, _ := session["id"].(string)
	dir, _ := session["working_directory"].(string)
	name, _ := harness["name"].(string)
	if id == "" || dir == "" || name == "" {
		return
	}
	decision := shareauto.ForHook(ShareSettingsPath(), dir)
	if !decision.Enabled {
		return
	}
	recordPath := activesession.DefaultPath()
	markedAt := time.Now()
	first, err := activesession.MarkShareRequested(recordPath, name, id, markedAt)
	if err != nil || !first {
		return
	}
	fields := map[string]interface{}{
		"session": map[string]interface{}{"id": id, "working_directory": dir},
	}
	if visibility := decision.Visibility; visibility == "public" || visibility == "direct" || visibility == "private" {
		fields["share"] = map[string]interface{}{"visibility": visibility}
	}
	if repo, _ := event["repository"].(string); repo != "" {
		fields["repository"] = repo
	}
	if branch, _ := event["branch"].(string); branch != "" {
		fields["branch"] = branch
	}
	if err := l.EndpointEventWithFidelity(asymptoteobserve.ActionShareRequested, "session", "info", "Auto-share requested for this session", asymptoteobserve.FidelityInferred, fields); err != nil {
		// The request was not written (a read-only log, a sandbox): take the mark back so the next
		// hook of the session asks again, rather than leave the session marked and never requested.
		// Like the rest of this path it stays silent and never fails the hook.
		_ = activesession.UnmarkShareRequested(recordPath, name, id, markedAt)
	}
}

// recordActiveSession notes the event's session as the one its runtime is running in its working
// directory, for `beacon share --current`. It is a local file write and never fails the hook: the
// record is a convenience, the event above is what matters. Nothing here touches the network.
func recordActiveSession(event map[string]interface{}) {
	session, _ := event["session"].(map[string]interface{})
	harness, _ := event["harness"].(map[string]interface{})
	if session == nil || harness == nil {
		return
	}
	id, _ := session["id"].(string)
	dir, _ := session["working_directory"].(string)
	name, _ := harness["name"].(string)
	if id == "" || dir == "" || name == "" {
		return
	}
	// Silent on failure: stderr is shown to the person on some runtimes, and a missing record
	// only means `beacon share --current` falls back to the newest session in the directory.
	_ = activesession.Record(activesession.DefaultPath(), name, id, dir, time.Now())
}

// stageInWorkspaceSpool stages one event this hook could not write to the runtime log at logPath
// in its session's workspace spool (asymptoteobserve.WorkspaceSpoolDir), and reports whether it
// did.
//
// Every harness stages, because every harness's spool has a drain: the sweep, `beacon endpoint
// spool drain`, and the session's own next hook that reaches the log. It began as DeepSeek
// Harness's alone (#605) and became general once other sandboxes showed the same shape (#1284).
// The session id and harness name must be safe directory names on BOTH the writing and the
// draining side (ValidSpoolName is what they share), so a hook without a session id stages
// nothing. The workspace comes from the event's own session.working_directory -- the directory a
// sandbox confines writes to -- with the process cwd as the fallback for callers that did not
// carry the field.
//
// An action only Beacon writes (IsBeaconOnlyAction) is never staged: every drain refuses it, as it
// must refuse one a repository planted, so staging would only turn a write the caller can retry
// (requestShareOnce takes its mark back) into one silently lost.
//
// The spool is a localingest.Spool, the store a restricted-mode hook already falls back to, not the
// runtime log's writer: it is private to this account wherever the workspace lives, bounded, and
// waits at most its short lock timeout for a drain under way, so a hook never holds the agent up
// behind one. A hook running as root never stages in a workspace another account owns
// (rootInAnotherAccountsWorkspace): that account could never drain the root-owned files.
func (l *Logger) stageInWorkspaceSpool(event map[string]interface{}, logPath string) bool {
	if l == nil || l.sessionID == "" {
		return false
	}
	if info, _ := event["event"].(map[string]interface{}); info != nil {
		if action, _ := info["action"].(string); asymptoteobserve.IsBeaconOnlyAction(action) {
			return false
		}
	}
	harness := asymptoteobserve.NormalizeHarnessName(l.platform)
	workspace := spoolWorkspace(event)
	dir, ok := asymptoteobserve.WorkspaceSpoolDir(workspace, harness, l.sessionID)
	// A workspace on the sandbox's own root filesystem (a cwd the sandbox never mounted) would
	// hold the spool only as long as the sandbox lives.
	if !ok || rootInAnotherAccountsWorkspace(workspace) || asymptoteobserve.OnSandboxRoot(dir) || !spoolPathIsReal(dir, true) {
		return false
	}
	line, err := encodeEndpointLine(event)
	if err != nil {
		return false
	}
	// <ws>/.beacon/spool, two levels above <harness>/<session>. Nothing is staged unless its
	// .gitignore keeps the spool out of git (ensureSpoolGitignore).
	spoolRoot := filepath.Dir(filepath.Dir(dir))
	if !ensureSpoolGitignore(spoolRoot) {
		return false
	}
	spool := localingest.Spool{Dir: dir}
	pending, _, err := spool.Pending()
	first := err != nil || pending == 0
	if dropped, err := spool.Append([][]byte{line}); err != nil || dropped > 0 {
		return false
	}
	ensureSpoolGitExclude(spoolRoot)
	if first {
		reportStagedSession(os.Stderr, harness, l.sessionID, logPath, dir, workspace)
	}
	return true
}

// reportStagedSession prints, once for each session's spool (when it starts holding events), where
// this session's events now wait and what delivers them. Not on every event: a hook runs as one
// process per event, and every note lands in the runtime's hook stderr stream. Nothing tells the
// hook whether a drain will find the session -- that needs Beacon to have recorded it outside the
// sandbox, or the workspace under workspace_spool_roots -- so the note names the drain the person
// can always run. That command names this session alone and the log this hook writes, shell-quoted
// to paste as it is: pasted, it vouches for one session, never for every spool a cloned repository
// planted beside it, and delivers to the log the hook meant, whatever mode the command runs in.
// DeepSeek Harness is the exception: `beacon endpoint dsh sync` finds its sessions through its own
// store, so its staging stays silent as it always was.
func reportStagedSession(w io.Writer, harness, sessionID, logPath, dir, workspace string) {
	if harness == dshHarnessName {
		return
	}
	fmt.Fprintf(w, "beacon-hooks: cannot write the Beacon runtime log %s here; this session's events are held in %s until Beacon drains them.\n", logPath, dir)
	fmt.Fprintf(w, "beacon-hooks: they are delivered by this session's next hook that reaches the log, or by running this outside the sandbox: beacon endpoint spool drain --log-path %s --workspace %s --harness %s --session %s\n",
		shellQuote(logPath), shellQuote(workspace), shellQuote(harness), shellQuote(sessionID))
}

// shellQuote quotes s for a POSIX shell, so a path with spaces, quotes or `$(...)` pastes as one
// literal argument.
func shellQuote(s string) string {
	return "'" + strings.ReplaceAll(s, "'", `'\''`) + "'"
}

// spoolWorkspace is the workspace an event's session runs in: its session.working_directory, or
// the process cwd when the caller did not carry one.
func spoolWorkspace(event map[string]interface{}) string {
	cwd := ""
	if session, ok := event["session"].(map[string]interface{}); ok {
		cwd, _ = session["working_directory"].(string)
	}
	if strings.TrimSpace(cwd) == "" {
		cwd, _ = os.Getwd()
	}
	return cwd
}

// spoolPathIsReal reports whether the components WorkspaceSpoolDir adds below the workspace --
// .beacon, spool, <harness> and <session> -- are real directories and the spool file, if present,
// a regular file no larger than a spool can grow. allowMissing lets components that do not exist
// yet pass, for a writer that creates them.
//
// The sandboxed agent can write the workspace and knows its own session id, so it can plant the
// session directory as a link to the account's own spool; the hook's drain, running outside the
// sandbox, would then remove the lines it refuses from that spool. Spool.Append never lets the
// file outgrow DefaultSpoolMaxBytes, so a larger one was written by hand and is not read. Lstat
// checks the components themselves, from the session directory up, so a missing spool costs a
// drain one stat.
func spoolPathIsReal(dir string, allowMissing bool) bool {
	file := localingest.Spool{Dir: dir}.FilePath()
	for i := 0; i < 4; i, dir = i+1, filepath.Dir(dir) {
		info, err := os.Lstat(dir)
		switch {
		case err == nil:
			if !info.IsDir() {
				return false
			}
		case allowMissing && os.IsNotExist(err):
		default:
			return false
		}
	}
	info, err := os.Lstat(file)
	return err != nil || (info.Mode().IsRegular() && info.Size() <= localingest.DefaultSpoolMaxBytes)
}

// ownSpoolDrainBatch bounds how many staged lines one hook delivers, so a long-sandboxed session's
// backlog never makes a single hook slow; what is left waits for a sweep or a later process.
const ownSpoolDrainBatch = 256

// drainedOwnSpools remembers the spool directories this process has already drained, so a hook
// that emits several events drains once rather than once per event.
var drainedOwnSpools sync.Map

// drainOwnWorkspaceSpool delivers, after this hook reached the runtime log at path, one batch of
// what earlier hooks of the same session staged when they could not -- a session that leaves its
// sandbox, or whose log comes back, catches up without waiting for a sweep.
//
// Only this hook's own session spool is drained: the hook knows its own session id is genuine, and
// cannot know that of any other directory under the workspace, which anything able to write the
// workspace (a cloned repository included) may have planted. Lines are untrusted all the same, so
// each passes AdmitStagedLine first; a refused one counts as processed, discarded rather than
// retried forever. A delivery error leaves it and the rest staged for the next drain.
//
// Everything here is best-effort and quiet: it never stages, never goes back through
// EndpointEventWithFidelity, never writes stderr and never fails the hook. It drains only through
// real directories (spoolPathIsReal), and Spool.Drain skips without waiting when another drainer
// holds the spool. Each admitted line is decoded and written again through encodeEndpointLine, as
// every line this hook writes is -- redacted, size-capped and stamped -- never appended byte for
// byte. Like staging, a hook running as root never drains in a workspace another account owns:
// the rewrite would leave that account's pending.jsonl root's.
func (l *Logger) drainOwnWorkspaceSpool(path string, event map[string]interface{}) {
	if l == nil || l.sessionID == "" {
		return
	}
	harness := asymptoteobserve.NormalizeHarnessName(l.platform)
	workspace := spoolWorkspace(event)
	dir, ok := asymptoteobserve.WorkspaceSpoolDir(workspace, harness, l.sessionID)
	if !ok || rootInAnotherAccountsWorkspace(workspace) {
		return
	}
	if _, done := drainedOwnSpools.LoadOrStore(dir, true); done || !spoolPathIsReal(dir, false) {
		return
	}
	_, _ = localingest.Spool{Dir: dir}.Drain(ownSpoolDrainBatch, func(lines [][]byte) (int, error) {
		for i, line := range lines {
			if !asymptoteobserve.AdmitStagedLine(line, harness, l.sessionID) {
				continue
			}
			var staged map[string]interface{}
			if err := json.Unmarshal(line, &staged); err != nil {
				continue
			}
			encoded, err := encodeEndpointLine(staged)
			if err != nil {
				continue
			}
			if err := deliverEndpointLine(path, encoded); err != nil {
				return i, err
			}
		}
		return len(lines), nil
	})
}

// reportedWriteFailures remembers which runtime log paths this process has already explained a
// write failure for, so the explanation is printed once per path rather than once per event. One
// hook invocation can emit several events -- a post-tool hook records the tool result, the file
// edit and the command in turn -- and a runtime that shows hook stderr to the person at the
// keyboard would otherwise repeat the same paragraph for each.
var reportedWriteFailures sync.Map

// reportEndpointWriteFailure explains, on stderr, that an endpoint event was not recorded and what
// to do about it.
//
// The one-line error above it names the path and the errno, which is enough for someone reading a
// log and not enough for someone watching a hook fail: "read-only file system" from inside an
// agent's sandbox reads like a broken disk, not like a runtime that confines its hooks.
//
// The exit status is deliberately not changed. Every hook path exits 0 (see the policy seam and
// the per-runtime deny notes in cmd/policy.go), and on the Claude-shaped hook contract DeepSeek
// Harness and several others reproduce, exit 2 is a *block*: it would refuse the tool call, erase
// the prompt, or -- on Stop -- keep the agent running, on every event, for as long as the log stays
// unwritable. A telemetry write that failed must never become a control decision, so the failure is
// made loud here, on the stream a runtime shows or logs for a hook, and detectable from outside by
// `beacon endpoint doctor`, which is where an operator can act on it.
func reportEndpointWriteFailure(w io.Writer, platform, path string, err error) {
	if w == nil || err == nil {
		return
	}
	if _, already := reportedWriteFailures.LoadOrStore(path, true); already {
		return
	}
	fmt.Fprintf(w, "beacon-hooks: this event was NOT recorded: cannot write the Beacon runtime log %s (%v).\n", path, err)
	if asymptoteobserve.NormalizeHarnessName(platform) == dshHarnessName {
		// DeepSeek Harness runs hook commands sandboxed to the session's working directory in
		// every sandbox mode except danger-full-access, and its sandbox policy has no writable-path
		// allow-list, so a log under the user's home is unreachable from a hook by design (#605).
		fmt.Fprintln(w, "beacon-hooks: DeepSeek Harness runs hooks inside the session sandbox, which can write only the session workspace unless the sandbox mode is danger-full-access; if this session is sandboxed, that is the cause and live hook capture is off for it.")
		fmt.Fprintln(w, "beacon-hooks: run `beacon endpoint dsh sync` outside the harness to backfill this session from DeepSeek's own session store, and `beacon endpoint doctor` to check hook capture.")
		return
	}
	fmt.Fprintln(w, "beacon-hooks: check that this user can write that path (the hook may be running in a sandbox that confines writes), then run `beacon endpoint doctor`.")
}

// dshHarnessName is DeepSeek Harness's canonical harness.name.
const dshHarnessName = "deepseek_harness"

// normalizeEventModel canonicalizes event["model"] in place, the way the harness name is
// canonicalized in baseEndpointEvent and for the same reason: every token report groups by this
// field, so one model reported under two spellings is two rows in the BY MODEL rollup.
//
// It runs after the caller's fields are merged rather than inside each mapper because every hook
// platform sets fields["model"] from its own payload -- Cline reads modelId, OpenCode reads a
// nested model object, the shared path reads "model" -- and normalizing in one place is what
// keeps a new mapper from quietly reintroducing the split.
//
// The provider prefix that normalizing removes is not dropped: it is recorded as
// gen_ai.provider.name when the runtime did not already report one, so "anthropic/claude-..."
// loses nothing by being canonicalized. An existing provider always wins, since the runtime
// naming its own provider is a better source than a prefix parsed out of a model string.
func normalizeEventModel(event map[string]interface{}) {
	raw, ok := event["model"].(string)
	if !ok || strings.TrimSpace(raw) == "" {
		return
	}
	name, provider := asymptoteobserve.SplitModelProvider(raw)
	event["model"] = name
	if provider == "" {
		return
	}
	genAI, _ := event["gen_ai"].(map[string]interface{})
	if genAI == nil {
		genAI = map[string]interface{}{}
	}
	providerBlock, _ := genAI["provider"].(map[string]interface{})
	if providerBlock == nil {
		providerBlock = map[string]interface{}{}
	}
	if existing, _ := providerBlock["name"].(string); strings.TrimSpace(existing) != "" {
		return
	}
	providerBlock["name"] = provider
	genAI["provider"] = providerBlock
	event["gen_ai"] = genAI
}

func (l *Logger) baseEndpointEvent(action, category, severity, message, fidelity string) map[string]interface{} {
	hostname, _ := os.Hostname()
	userName := os.Getenv("USER")
	user := map[string]interface{}{
		"name": userName,
	}
	if uid := firstEnv("BEACON_CLOUD_USER_ID_HASH", "BEACON_CLOUD_USER_ID"); uid != "" {
		user["uid"] = uid
	} else if current, err := osuser.Current(); err == nil {
		user["uid"] = current.Uid
		if userName == "" {
			user["name"] = current.Username
		}
	}
	// Both blocks are assembled before the event literal so the provenance keys can be omitted
	// rather than written empty. This path builds raw maps instead of the shared Event struct, so
	// it does not get `omitempty` for free, and an empty "collection_method" on every event would
	// be both noise in the log and a value a consumer could mistake for a real one.
	eventBlock := map[string]interface{}{
		"kind":     "agent_runtime",
		"action":   action,
		"category": category,
	}
	if fidelity != "" {
		eventBlock["fidelity"] = fidelity
	}
	harnessBlock := map[string]interface{}{
		// Normalized rather than written raw. The OTLP path already reports the canonical name
		// for the same session, so emitting the raw --platform value here recorded one session
		// under two names -- splitting it for any query or SIEM detection that groups by
		// harness.name. The flag itself is unchanged, so existing installs are fixed without
		// having their settings.json rewritten.
		"name": asymptoteobserve.NormalizeHarnessName(l.platform),
	}
	// Derived from --platform rather than from the normalized name above, because the flag is what
	// records which integration shape is installed. The two differ for VS Code, whose hook and
	// OTLP telemetry share a harness name.
	if method := asymptoteobserve.CollectionMethodForPlatform(l.platform); method != "" {
		harnessBlock["collection_method"] = method
	}
	event := map[string]interface{}{
		"timestamp": asymptoteobserve.FormatTimestamp(time.Now()),
		// Emission order within this hook invocation. One invocation can emit several
		// events (a post-tool hook records the tool result, the file edit and the command
		// in turn), and on a coarse clock those can land on the same nanosecond -- the
		// counter is what still separates them. It restarts at 1 in every hook process,
		// which is why it is a tiebreaker under the timestamp rather than an ordering key
		// of its own; see asymptoteobserve.Event.Sequence.
		"sequence":       endpointSequence.Next(),
		"vendor":         "beacon",
		"product":        "endpoint-agent",
		"schema_version": "1.0",
		"event":          eventBlock,
		"severity":       severity,
		"endpoint": map[string]interface{}{
			"hostname": hostname,
			"os":       runtime.GOOS,
		},
		"user":    user,
		"harness": harnessBlock,
		"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 attachDerivedTrace(event map[string]interface{}) {
	if event == nil {
		return
	}
	session, _ := event["session"].(map[string]interface{})
	sessionID, _ := session["id"].(string)
	if strings.TrimSpace(sessionID) == "" {
		return
	}
	trace, _ := event["trace"].(map[string]interface{})
	if trace == nil {
		trace = map[string]interface{}{}
	}
	if id, _ := trace["id"].(string); strings.TrimSpace(id) == "" {
		harness, _ := event["harness"].(map[string]interface{})
		harnessName, _ := harness["name"].(string)
		if traceID := asymptoteobserve.DerivedTraceIDForSession(harnessName, sessionID); traceID != "" {
			trace["id"] = traceID
		}
	}
	if spanID, _ := trace["span_id"].(string); strings.TrimSpace(spanID) == "" {
		if callID := endpointToolCallID(event); callID != "" {
			trace["span_id"] = callID
		}
	}
	if len(trace) > 0 {
		event["trace"] = trace
	}
}

func endpointToolCallID(event map[string]interface{}) string {
	genAI, _ := event["gen_ai"].(map[string]interface{})
	tool, _ := genAI["tool"].(map[string]interface{})
	call, _ := tool["call"].(map[string]interface{})
	id, _ := call["id"].(string)
	return strings.TrimSpace(id)
}

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 ""
}

// writeEndpointJSON appends one endpoint event to the runtime log. A variable so a test can make one
// write fail.
var writeEndpointJSON = writeEndpointJSONFile

func writeEndpointJSONFile(path string, event map[string]interface{}) error {
	_, dirMode, _ := asymptoteobserve.RuntimeLogModes(path)
	if asymptoteobserve.RuntimeLogDirCreatable(path) {
		if err := os.MkdirAll(filepath.Dir(path), dirMode); err != nil {
			return err
		}
	}
	data, err := encodeEndpointLine(event)
	if err != nil {
		return err
	}
	return deliverEndpointLine(path, data)
}

// encodeEndpointLine is the line an endpoint event is written as: sanitized, then fitted to the
// event size limit and stamped with its event.id the way every writer does (FitEventLine).
func encodeEndpointLine(event map[string]interface{}) ([]byte, error) {
	data, err := json.Marshal(sanitizeEndpointMap(event))
	if err != nil {
		return nil, err
	}
	var stamp func(id string) ([]byte, error)
	if info, ok := event["event"].(map[string]interface{}); ok {
		if id, _ := info["id"].(string); strings.TrimSpace(id) == "" {
			stamp = func(id string) ([]byte, error) {
				info["id"] = id
				return json.Marshal(sanitizeEndpointMap(event))
			}
		}
	}
	return asymptoteobserve.FitEventLine(data, asymptoteobserve.DefaultMaxEventBytes, stamp)
}

// EndpointIngest delivers to the system log through the collector when the endpoint is in the
// restricted log access mode. Tests point it at a socket and spool of their own; nothing else
// changes it.
var EndpointIngest = defaultEndpointIngest()

// defaultEndpointIngest is the real socket and the account's spool, except in a test binary, where
// a test writing a system log as an ordinary account must never reach the machine's collector or
// leave lines in the developer's own spool.
func defaultEndpointIngest() localingest.Deliverer {
	if !testing.Testing() {
		return localingest.Deliverer{}
	}
	dir := filepath.Join(os.TempDir(), fmt.Sprintf("beacon-hooks-test-%d", os.Getpid()))
	socket := filepath.Join(dir, "no-collector.sock")
	if runtime.GOOS == "windows" {
		socket = fmt.Sprintf(`\\.\pipe\beacon-hooks-test-%d-none`, os.Getpid())
	}
	return localingest.Deliverer{
		Client: localingest.Client{SocketPath: socket},
		Spool:  localingest.Spool{Dir: filepath.Join(dir, "spool")},
	}
}

// deliverEndpointLine writes one finished line to the runtime log at path.
//
// A hook writing the system log as an ordinary account hands the line to the collector over the
// local ingest socket when the endpoint has one (the restricted log access mode, in which the log
// is not writable by this account at all), and otherwise appends directly, as hooks always have.
// Only a direct append the log refuses -- a restricted endpoint whose collector is restarting --
// puts the line in this account's private spool, and it reaches the log with a later event
// instead of being lost. Root and per-user logs are always written directly. See
// localingest.Deliverer.Write.
func deliverEndpointLine(path string, data []byte) error {
	return EndpointIngest.Write(path, data, func(line []byte) error {
		return appendEndpointJSONL(path, append(line[:len(line):len(line)], '\n'), defaultEndpointRotateBytes, defaultEndpointRotateArchives)
	})
}

// EndpointLogConfigured reports whether this process has a runtime log to write to. Without one,
// EndpointEvent records nothing and returns nil, so a caller reporting what it recorded checks this
// rather than reading a nil error as a write.
func EndpointLogConfigured() bool {
	return endpointLogPath() != ""
}

func endpointLogPath() string {
	if path := firstEnv("BEACON_ENDPOINT_LOG", "BEACON_CLOUD_LOG_PATH", "BEACON_LOG_PATH", "BEACON_RUNTIME_LOG"); path != "" {
		return path
	}
	if os.Getenv("BEACON_ENDPOINT_MODE") == "" {
		return ""
	}
	home, err := os.UserHomeDir()
	if err != nil {
		return ""
	}
	return filepath.Join(home, ".beacon", "endpoint", "logs", "runtime.jsonl")
}

func sanitizeEndpointMap(input map[string]interface{}) map[string]interface{} {
	return asymptoteobserve.SanitizeMap(input, asymptoteobserve.PrivacyOptions{
		RedactSecrets: true,
		StringLimit:   asymptoteobserve.DefaultStringLimit,
	})
}

func sanitizeEndpointSlice(input []interface{}) []interface{} {
	return asymptoteobserve.SanitizeSlice(input, asymptoteobserve.PrivacyOptions{
		RedactSecrets: true,
		StringLimit:   asymptoteobserve.DefaultStringLimit,
	})
}

// Keep this file-mode contract mirrored with the endpoint CLI and beaconjson exporter; the rotation
// itself is asymptoteobserve.RotateRuntimeLog for all three.
func appendEndpointJSONL(path string, line []byte, rotateBytes int64, rotateArchives int) error {
	_, dirMode, _ := asymptoteobserve.RuntimeLogModes(path)
	if asymptoteobserve.RuntimeLogDirCreatable(path) {
		if err := os.MkdirAll(filepath.Dir(path), dirMode); err != nil {
			return err
		}
	}
	lock, err := openEndpointRuntimeFileAs(path+".lock", path, os.O_CREATE|os.O_RDWR)
	if err != nil {
		return err
	}
	held, err := filelock.Exclusive(lock)
	if err != nil {
		_ = lock.Close()
		return err
	}
	// Unlock before closing: LIFO defer ordering means the close listed first runs last.
	defer lock.Close()
	defer held.Release()
	if asymptoteobserve.IsDuplicateEndpointEvent(path, line, asymptoteobserve.EndpointDuplicateWindow) {
		return nil
	}
	// A rotation that cannot happen now is deferred, never fatal, and the event is appended past the
	// size limit for a later write to rotate. A hook usually runs as the person at the keyboard, and
	// on a system-mode log it may not rename or delete anything in the directory: the directory is
	// root-owned 0755 on POSIX, and on Windows its ACL gives ordinary users no right to add, rename or
	// delete entries -- the rights that would let one redirect a SYSTEM write. Rotation is the
	// privileged writers' job there. And on Windows a reader holding the log open without delete
	// sharing blocks the rename for every writer until it lets go. asymptoteobserve.RotateRuntimeLog
	// moves nothing in either case.
	_ = asymptoteobserve.RotateRuntimeLog(path, rotateBytes, rotateArchives, int64(len(line)))
	f, err := openEndpointRuntimeFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY)
	if err != nil {
		return err
	}
	defer f.Close()
	_, err = f.Write(line)
	return err
}

func openEndpointRuntimeFile(path string, flag int) (*os.File, error) {
	return openEndpointRuntimeFileAs(path, path, flag)
}

// openEndpointRuntimeFileAs opens path (the log or its lock) with the mode logPath calls for, and
// settles its mode through asymptoteobserve.OpenRuntimeLogFile: a new file gets that mode
// whatever the umask, an existing one is only ever narrowed toward it, by its owner, and root never
// follows a symlink or opens anything but a regular file there.
func openEndpointRuntimeFileAs(path, logPath string, flag int) (*os.File, error) {
	return asymptoteobserve.OpenRuntimeLogFile(path, logPath, flag)
}

// Debug logs a debug message
func (l *Logger) Debug(message string, fields ...interface{}) {
	entry := l.formatEntry("debug", message, fields...)
	l.write(entry)
}

// Info logs an info message
func (l *Logger) Info(message string, fields ...interface{}) {
	entry := l.formatEntry("info", message, fields...)
	l.write(entry)
}

// Warn logs a warning message
func (l *Logger) Warn(message string, fields ...interface{}) {
	entry := l.formatEntry("warn", message, fields...)
	l.write(entry)
}

// Error logs an error message and also writes to stderr
func (l *Logger) Error(message string, fields ...interface{}) {
	entry := l.formatEntry("error", message, fields...)
	l.write(entry)
	fmt.Fprintf(os.Stderr, "[%s] ERROR: %s\n", l.hookName, message)
}