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
// __BEACON_MANAGED_MARKER__
// Beacon endpoint telemetry plugin for opencode.
// Managed by beacon endpoint hooks install --harness opencode.
import { appendFile, mkdir } from "node:fs/promises"
import { homedir } from "node:os"
import { dirname, join } from "node:path"
const beaconCommand = "__BEACON_COMMAND__"
const pluginID = "beacon.endpoint"
const debugEnabled = process.env.BEACON_OPENCODE_DEBUG === "1"
// OpenCode 2.x gives plugins no logger and discards the server's stderr unless it runs
// standalone with --print-logs, so debug lines without client.app.log go to this file.
const debugFile = join(homedir(), ".beacon", "endpoint", "logs", "opencode-plugin-debug.log")
const sendTimeoutMs = 2000
const directHookTypes = new Set([
"chat.message",
"command.execute.before",
"tool.execute.before",
"tool.execute.after",
])
const forwardedEvents = new Set([
"message.part.updated",
"message.part.delta",
"message.updated",
"permission.v2.asked",
"permission.v2.replied",
"session.created",
"session.deleted",
"session.idle",
"session.status",
"session.error",
"session.diff",
"command.executed",
"permission.asked",
"permission.replied",
"permission.updated",
])
async function debugLog(client, message, extra) {
if (!debugEnabled) return
try {
if (typeof client?.app?.log === "function") {
await client.app.log({
body: {
service: "beacon-opencode-plugin",
level: "debug",
message,
extra,
},
})
return
}
await mkdir(dirname(debugFile), { recursive: true, mode: 0o700 })
await appendFile(debugFile, JSON.stringify({ time: new Date().toISOString(), message, extra }) + "\n", {
mode: 0o600,
})
} catch {
// Debug logging must stay best-effort.
}
}
async function sendToBeacon(client, payload) {
const testSender = globalThis[Symbol.for("beacon.opencode.testSender")]
if (typeof testSender === "function") {
await testSender(payload)
return
}
let proc
try {
proc = Bun.spawn(["/bin/sh", "-lc", beaconCommand], {
stdin: "pipe",
stdout: "ignore",
stderr: "ignore",
})
proc.stdin.write(JSON.stringify(payload))
proc.stdin.end()
const outcome = await Promise.race([
proc.exited.then((code) => ({ code })),
Bun.sleep(sendTimeoutMs).then(() => ({ timeout: true })),
])
if ("timeout" in outcome) {
proc.kill()
await Promise.race([proc.exited.catch(() => undefined), Bun.sleep(250)])
await debugLog(client, "Beacon hook command timed out", { type: payload?.type })
return
}
const code = outcome.code
if (code !== 0) {
await debugLog(client, "Beacon hook command exited non-zero", { code, type: payload?.type })
}
} catch (err) {
await debugLog(client, "Beacon hook command failed", {
error: err instanceof Error ? err.message : String(err),
type: payload?.type,
})
// Beacon telemetry must never interrupt opencode execution.
}
}
function sessionID(value) {
const direct = value?.sessionID || value?.session_id || value?.session?.id || value?.info?.sessionID
if (direct) return direct
if (typeof value?.id === "string" && value.id.startsWith("ses_")) return value.id
if (typeof value?.info?.id === "string" && value.info.id.startsWith("ses_")) return value.info.id
return ""
}
function modelName(value) {
if (value?.providerID && value?.modelID) return value.providerID + "/" + value.modelID
const model = value?.model || value?.modelInfo
if (!model || typeof model === "string") return model || ""
if (model.providerID && model.modelID) return model.providerID + "/" + model.modelID
return model.modelID || model.id || model.name || ""
}
function filePath(value) {
return (
value?.filePath ||
value?.file_path ||
value?.path ||
value?.file ||
value?.target ||
value?.destination ||
""
)
}
function isFileMutationTool(tool) {
const name = String(tool || "").toLowerCase()
const tokens = name.split(/[^a-z0-9]+/).filter(Boolean)
return (
["edit", "write", "patch", "create"].some((part) => tokens.includes(part)) ||
["applypatch", "multiedit"].includes(name)
)
}
function shellMutationPaths(tool, args) {
const name = String(tool || "").toLowerCase()
if (name !== "bash" && !name.includes("shell")) return []
const command = String(args?.command || args?.cmd || "")
const paths = []
// Operands end at a separator or a redirection; `2>/dev/null` is not a path.
const operand = /[ \t]+(?:"([^"]+)"|'([^']+)'|([^\s;&|<>"']+))(?=[\s;&|]|$)/y
const pattern = /(?:(?:^|&&|\|\||;|\n)[ \t]*)(?:sudo\s+)?(?:command\s+)?(?:\/bin\/)?(?:rm|unlink)(?=[ \t])/g
for (const match of command.matchAll(pattern)) {
operand.lastIndex = match.index + match[0].length
let options = true
for (let arg = operand.exec(command); arg; arg = operand.exec(command)) {
const bare = arg[3]
// A comment ends the command, and a command substitution is another command.
if (bare?.startsWith("#") || /\$\(|`/.test(arg[0])) break
if (options && bare === "--") {
options = false
continue
}
if (options && bare?.startsWith("-")) continue
// A variable or glob is not a path this can know, and a wrong path is worse than none.
if (/\$/.test(arg[1] || "") || (bare && /[$*?[]|^~/.test(bare))) continue
const path = arg[1] || arg[2] || bare
if (path) paths.push(path)
}
}
return paths
}
export const BeaconEndpointPlugin = async ({ project, directory, worktree, client }) => {
const context = { project, directory, worktree }
const activeCalls = new Map()
const completedCalls = new Map()
const emittedParts = new Set()
const pendingParts = new Map()
const partDeltas = new Map()
const messageModels = new Map()
const messageRoles = new Map()
const messageSessions = new Map()
const completedMessages = new Set()
const permissionRequests = new Map()
const sessionStates = new Map()
const recentFilePaths = new Map()
let eventQueue = Promise.resolve()
const payload = (type, values = {}) => ({ type, ...values, ...context })
const enqueue = (value) => {
eventQueue = eventQueue
.then(() => sendToBeacon(client, value))
.catch((err) => debugLog(client, "Beacon event queue failed", { error: String(err), type: value?.type }))
return eventQueue
}
// Only the caller times out; ordered delivery still governs session cleanup.
const enqueueDirect = (value) => {
const completed = enqueue(value)
let timer
const deadline = new Promise((resolve) => { timer = setTimeout(resolve, sendTimeoutMs) })
return Promise.race([completed, deadline]).finally(() => clearTimeout(timer))
}
const rememberFilePath = (tool, args, sid, callID, includeShell = false) => {
const paths = []
if (isFileMutationTool(tool) && filePath(args)) paths.push(filePath(args))
if (includeShell) paths.push(...shellMutationPaths(tool, args))
for (const path of paths) recentFilePaths.set(path, { time: Date.now(), sessionID: sid, callID })
}
const partKey = (part, fallbackSessionID) =>
`${part?.sessionID || fallbackSessionID || ""}:${part?.messageID || ""}:${part?.id || ""}`
const emitPart = (part, sid, model) => {
if (!part) return
const key = partKey(part, sid)
if (emittedParts.has(key)) return
const next = structuredClone(part)
const delta = partDeltas.get(key)
if ((next.type === "text" || next.type === "reasoning") && !next.text && delta) next.text = delta
if ((next.type === "text" || next.type === "reasoning") && typeof next.text === "string") partDeltas.set(key, next.text)
if (next.type === "tool") {
const status = next.state?.status
if (status !== "completed" && status !== "error") return
// A failed tool never reaches tool.execute.after, which is what releases its arguments.
if (status === "error") activeCalls.delete(next.callID)
if (status === "completed" && completedCalls.has(next.callID)) return
} else if (next.type === "text" || next.type === "reasoning") {
if (next.type === "text") {
const role = messageRoles.get(next.messageID)
if (role === "user") {
emittedParts.add(key)
pendingParts.delete(key)
partDeltas.delete(key)
return
}
if (role !== "assistant") {
pendingParts.set(key, { part: next, session_id: sid, model })
return
}
}
if (!next.time?.end) {
pendingParts.set(key, { part: next, session_id: sid, model })
return
}
} else if (next.type !== "retry") {
return
}
emittedParts.add(key)
pendingParts.delete(key)
partDeltas.delete(key)
void enqueue(payload("message.part.updated", { session_id: sid, model, part: next }))
}
const flushParts = (sid) => {
for (const [key, item] of [...pendingParts]) {
if (item.session_id !== sid) continue
const part = { ...item.part, time: { ...(item.part.time || {}), end: Date.now() } }
pendingParts.delete(key)
emitPart(part, sid, item.model)
}
}
const flushMessageParts = (messageID, sid, model, completedAt) => {
for (const [key, item] of [...pendingParts]) {
if (item.part?.messageID !== messageID) continue
const part = { ...item.part, time: { ...(item.part.time || {}), end: completedAt || Date.now() } }
pendingParts.delete(key)
emitPart(part, sid, model || item.model)
}
}
const cleanupSession = (sid) => {
for (const [callID, item] of activeCalls) if (item.session_id === sid) activeCalls.delete(callID)
for (const [callID, session] of completedCalls) if (session === sid) completedCalls.delete(callID)
for (const key of emittedParts) if (key.startsWith(`${sid}:`)) emittedParts.delete(key)
for (const [key, item] of pendingParts) if (item.session_id === sid) pendingParts.delete(key)
for (const key of partDeltas.keys()) if (key.startsWith(`${sid}:`)) partDeltas.delete(key)
for (const [messageID, session] of messageSessions) {
if (session !== sid) continue
messageSessions.delete(messageID)
messageModels.delete(messageID)
messageRoles.delete(messageID)
completedMessages.delete(messageID)
}
for (const [requestID, request] of permissionRequests) {
if (request.sessionID === sid) permissionRequests.delete(requestID)
}
sessionStates.delete(sid)
for (const [path, item] of recentFilePaths) if (item.sessionID === sid) recentFilePaths.delete(path)
}
return {
"chat.message": async (input, output) => {
if (output?.message?.id) {
messageRoles.set(output.message.id, "user")
messageSessions.set(output.message.id, sessionID(input))
}
await enqueueDirect({
type: "chat.message",
session_id: sessionID(input),
model: modelName(input),
input,
output,
...context,
})
},
"command.execute.before": async (input, output) => {
await enqueueDirect(
payload("command.execute.before", {
session_id: sessionID(input),
command_name: input?.command,
arguments: input?.arguments,
parts: output?.parts,
}),
)
},
"tool.execute.before": async (input, output) => {
const sid = sessionID(input)
activeCalls.set(input?.callID, {
tool: input?.tool,
args: structuredClone(output?.args || {}),
session_id: sid,
started_at: Date.now(),
})
rememberFilePath(input?.tool, output?.args || {}, sid, input?.callID)
await enqueueDirect(
payload("tool.execute.before", {
session_id: sessionID(input),
tool_name: input?.tool,
call_id: input?.callID,
tool_input: output?.args || {},
}),
)
},
"tool.execute.after": async (input, output) => {
const active = activeCalls.get(input?.callID)
const args = input?.args || active?.args || {}
const exitCode = output?.metadata?.exit ?? output?.metadata?.exitCode ?? output?.metadata?.exit_code
rememberFilePath(input?.tool, args, sessionID(input), input?.callID, exitCode === 0)
await enqueueDirect(
payload("tool.execute.after", {
session_id: sessionID(input),
tool_name: input?.tool,
call_id: input?.callID,
duration_ms: active?.started_at ? Date.now() - active.started_at : undefined,
tool_input: args,
tool_response: output,
file_mutations:
exitCode === 0
? shellMutationPaths(input?.tool, args).map((path) => ({ path, operation: "delete" }))
: [],
}),
)
activeCalls.delete(input?.callID)
completedCalls.set(input?.callID, sessionID(input))
},
event: async ({ event }) => {
const type = event?.type || "event"
if (!forwardedEvents.has(type)) return
const properties = event?.properties || event?.data || {}
const sid = sessionID(properties)
const info = properties?.info || {}
if (type === "message.updated") {
if (info?.id) {
if (info?.role) messageRoles.set(info.id, info.role)
messageSessions.set(info.id, sid)
}
if (info?.role !== "assistant") return
const model = modelName(info)
if (info?.id && model) messageModels.set(info.id, model)
if (!info?.time?.completed && !info?.error) return
flushMessageParts(info.id, sid, model, info?.time?.completed)
if (info?.id) {
if (completedMessages.has(info.id)) return
if (!info.finish || info.finish === "stop") completedMessages.add(info.id)
}
}
if (type === "message.part.delta") {
if (properties?.field && properties.field !== "text") return
const key = `${sid}:${properties?.messageID || ""}:${properties?.partID || ""}`
const text = (partDeltas.get(key) || "") + (properties?.delta || "")
partDeltas.set(key, text)
const pending = pendingParts.get(key)
if (pending && (pending.part.type === "text" || pending.part.type === "reasoning")) pending.part.text = text
return
}
if (type === "message.part.updated") {
const part = properties?.part
emitPart(part, sid, messageModels.get(part?.messageID) || "")
return
}
if (type === "session.status") {
const status = properties?.status?.type || ""
if (sessionStates.get(sid) === status) return
sessionStates.set(sid, status)
if (status === "idle") flushParts(sid)
}
if (type === "session.idle") {
flushParts(sid)
if (sessionStates.get(sid) === "idle") return
sessionStates.set(sid, "idle")
}
if (type === "session.deleted") flushParts(sid)
if (type === "permission.asked" || type === "permission.v2.asked") {
if (properties?.id) {
permissionRequests.set(properties.id, {
tool: properties?.tool,
permission: properties?.permission,
sessionID: sid,
})
}
}
if (type === "permission.replied" || type === "permission.v2.replied") {
const request = permissionRequests.get(properties?.requestID)
if (request?.tool && !properties.tool) properties.tool = request.tool
if (request?.permission && !properties.permission) properties.permission = request.permission
permissionRequests.delete(properties?.requestID)
}
if (type === "session.diff") {
const diffs = Array.isArray(properties?.diff) ? properties.diff : []
const now = Date.now()
const filtered = diffs.filter((item) => {
const path = filePath(item)
if (!path) return false
const seen = recentFilePaths.get(path)
if (seen && now - seen.time < 5000) return false
return item?.before !== item?.after || item?.additions || item?.deletions
})
if (filtered.length === 0) return
properties.diff = filtered
}
const queued = enqueue(
payload(type, {
session_id: sessionID(properties) || sid,
model: modelName(Object.keys(info).length > 0 ? info : properties),
properties,
event,
}),
)
if (type === "session.deleted") void queued.finally(() => cleanupSession(sid))
},
}
}
// OpenCode 2.x loads only a default definition with an id and a setup
// function; 1.x reads the same default export's server field. setup adapts
// the V2 hooks and event stream onto the V1 handlers above, so both runtimes
// send the same payloads to beacon-hooks.
function v2Model(ref) {
if (!ref?.id) return undefined
return ref.providerID ? { providerID: ref.providerID, modelID: ref.id } : { modelID: ref.id }
}
function v2PromptParts(prompt) {
const parts = []
if (prompt?.text) parts.push({ type: "text", text: prompt.text })
for (const file of prompt?.files || []) {
if (file?.uri) parts.push({ type: "file", filename: file.name || file.uri, url: file.uri })
}
for (const agent of prompt?.agents || []) {
if (agent?.name) parts.push({ type: "agent", name: agent.name })
}
return parts
}
function v2ToolResponse(result) {
const structured = result?.output
const text = (result?.content || [])
.filter((item) => item?.type === "text" && typeof item.text === "string")
.map((item) => item.text)
.join("\n")
const output = typeof structured === "string" ? structured : structured?.output ?? text
const metadata = { ...(result?.metadata || {}) }
if (metadata.exit === undefined && typeof structured?.exit === "number") metadata.exit = structured.exit
return { output, metadata }
}
// Translates one V2 event into the V1 {type, properties} events the handler
// understands. Tool success and failure arrive through the tool hooks instead.
function v2Events(event, models) {
const data = event?.data || {}
const sid = data.sessionID
const created = typeof event?.created === "number" ? event.created : Date.now()
switch (event?.type) {
case "session.created":
case "session.model.selected":
// The step is the one event that always names the model: OpenCode often creates a session
// before the plugin's event stream is subscribed, and a default model is never "selected".
case "session.step.started": {
const model = v2Model(data.model)
if (sid && model) models.set(sid, model)
if (event.type !== "session.created") return []
return [{ type: "session.created", properties: { ...data, info: { ...data, id: sid, ...(model || {}) } } }]
}
case "session.deleted":
case "session.idle":
case "session.status":
case "permission.replied":
return [{ type: event.type, properties: data }]
case "permission.asked":
return [
{
type: "permission.asked",
properties: { ...data, permission: data.action, patterns: data.resources },
},
]
case "session.execution.started":
return [{ type: "session.status", properties: { sessionID: sid, status: { type: "busy" } } }]
case "session.execution.succeeded":
case "session.execution.failed":
case "session.execution.interrupted": {
const events = []
if (event.type === "session.execution.failed") {
events.push({ type: "session.error", properties: { sessionID: sid, error: data.error } })
}
events.push({ type: "session.status", properties: { sessionID: sid, status: { type: "idle" } } })
return events
}
case "session.text.ended":
case "session.reasoning.ended": {
const messageID = data.assistantMessageID
const type = event.type === "session.text.ended" ? "text" : "reasoning"
return [
{
type: "message.updated",
properties: { sessionID: sid, info: { id: messageID, role: "assistant", sessionID: sid, ...(models.get(sid) || {}) } },
},
{
type: "message.part.updated",
properties: {
sessionID: sid,
part: {
id: `${messageID}:${type}:${data.ordinal ?? 0}`,
messageID,
sessionID: sid,
type,
text: data.text || "",
time: { start: created, end: created },
},
},
},
]
}
case "session.step.ended":
return [
{
type: "message.updated",
properties: {
sessionID: sid,
info: {
id: data.assistantMessageID,
role: "assistant",
sessionID: sid,
...(models.get(sid) || {}),
finish: data.finish,
tokens: data.tokens,
cost: data.cost,
time: { completed: created },
},
},
},
]
default:
return []
}
}
export default {
id: pluginID,
server: BeaconEndpointPlugin,
async setup(ctx) {
const location = ctx?.location || {}
const hooks = await BeaconEndpointPlugin({
project: location.project,
directory: location.directory,
worktree: location.project?.canonical || location.project?.directory || location.directory,
client: ctx,
})
const models = new Map()
const registrations = []
const registered = []
const register = async (domain, name, callback) => {
if (typeof domain?.hook !== "function") {
await debugLog(ctx, "Beacon V2 hook API unavailable", { name })
return
}
try {
const registration = await domain.hook(name, async (input) => {
try {
await callback(input)
} catch (err) {
await debugLog(ctx, "Beacon V2 hook failed", { name, error: String(err) })
}
})
if (registration) {
registrations.push(registration)
registered.push(name)
}
} catch (err) {
await debugLog(ctx, "Beacon V2 hook registration failed", { name, error: String(err) })
}
}
await register(ctx?.session, "prompt", (input) =>
hooks["chat.message"](
{ sessionID: input?.sessionID, messageID: input?.messageID, ...(models.get(input?.sessionID) || {}) },
{ message: { id: input?.messageID }, parts: v2PromptParts(input?.prompt) },
),
)
await register(ctx?.tool, "execute.before", (input) =>
hooks["tool.execute.before"](
{ sessionID: input?.sessionID, tool: input?.tool, callID: input?.id },
{ args: structuredClone(input?.input ?? {}) },
),
)
await register(ctx?.tool, "execute.after", async (input) => {
if (input?.status === "completed") {
await hooks["tool.execute.after"](
{ sessionID: input.sessionID, tool: input.tool, callID: input.id, args: input.input ?? {} },
v2ToolResponse(input.result),
)
return
}
const now = Date.now()
await hooks.event({
event: {
type: "message.part.updated",
properties: {
sessionID: input?.sessionID,
part: {
id: `${input?.messageID}:tool:${input?.id}`,
messageID: input?.messageID,
sessionID: input?.sessionID,
callID: input?.id,
type: "tool",
tool: input?.tool,
state: {
status: "error",
input: input?.input ?? {},
error: input?.error?.message || String(input?.error ?? "tool failed"),
time: { start: now, end: now },
},
},
},
},
})
})
await debugLog(ctx, "Beacon V2 setup complete", {
opencode: ctx?.app?.version,
hooks: registered,
events: typeof ctx?.event?.subscribe === "function",
})
const controller = new AbortController()
const consuming = (async () => {
if (typeof ctx?.event?.subscribe !== "function") return
for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
if (controller.signal.aborted) break
for (const translated of v2Events(event, models)) {
try {
await hooks.event({ event: translated })
} catch (err) {
await debugLog(ctx, "Beacon V2 event failed", { type: translated.type, error: String(err) })
}
}
if (event?.type === "session.deleted") models.delete(event?.data?.sessionID)
}
})().catch((err) => {
if (!controller.signal.aborted) void debugLog(ctx, "Beacon V2 event subscription failed", { error: String(err) })
})
return async () => {
controller.abort()
await consuming
await Promise.all(registrations.map((item) => Promise.resolve().then(() => item.dispose?.()).catch(() => undefined)))
}
},
}