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
import { afterEach, describe, expect, test } from "bun:test"
import entry, { createBeaconPlugin } from "./beacon.js"
const senderKey = Symbol.for("beacon.openclaw.testSender")
type Sent = Record<string, unknown>
function captureSends(): Sent[] {
const sent: Sent[] = []
;(globalThis as Record<symbol, unknown>)[senderKey] = (payload: Sent) => {
sent.push(payload)
}
return sent
}
type Handler = (event: Record<string, unknown>, ctx: unknown) => unknown
// A stand-in for OpenClaw's plugin API that records registrations and lets a test fire one.
function fakeGateway() {
const handlers = new Map<string, Handler>()
return {
api: {
on(hook: string, handler: Handler) {
handlers.set(hook, handler)
},
},
handlers,
async fire(hook: string, event: Record<string, unknown>, ctx?: unknown) {
const handler = handlers.get(hook)
if (!handler) throw new Error(`no handler registered for ${hook}`)
return await handler(event, ctx)
},
// fireSync returns whatever the handler returned without awaiting, which is how a test
// observes that a handler did not hand OpenClaw a promise to wait on.
fireSync(hook: string, event: Record<string, unknown>, ctx?: unknown) {
const handler = handlers.get(hook)
if (!handler) throw new Error(`no handler registered for ${hook}`)
return handler(event, ctx)
},
}
}
function context(overrides: Record<string, unknown> = {}) {
return {
sessionId: "sess-1",
sessionKey: "discord:chan-9",
runId: "run-7",
agentId: "main",
workspaceDir: "/workspace/repo",
modelProviderId: "openai",
modelId: "gpt-5",
channel: "discord",
...overrides,
}
}
afterEach(() => {
delete (globalThis as Record<symbol, unknown>)[senderKey]
// No cache reset is needed: pending derived paths live on the plugin instance, and every test
// builds its own.
})
describe("beacon openclaw plugin", () => {
// These strings are the contract between this plugin and the openclaw-event mapper in the hook
// adapter. A typo on either side produces no telemetry rather than an error, so the list is
// pinned here and asserted against the mapper's own list on the Go side.
test("registers exactly the hooks the mapper handles", () => {
const gateway = fakeGateway()
createBeaconPlugin().register(gateway.api)
expect([...gateway.handlers.keys()].sort()).toEqual([
"after_compaction",
"after_tool_call",
"before_compaction",
"before_tool_call",
"llm_output",
"message_received",
"session_end",
"session_start",
"subagent_ended",
"subagent_spawned",
])
})
test("the default export is a loadable plugin entry", () => {
const gateway = fakeGateway()
expect(entry.id).toBe("beacon-endpoint")
entry.register(gateway.api)
expect(gateway.handlers.size).toBe(10)
})
test("lifts session, run, workspace, and model identity onto the envelope", async () => {
const sent = captureSends()
const gateway = fakeGateway()
createBeaconPlugin().register(gateway.api)
await gateway.fire("session_start", { sessionId: "sess-1" }, context())
expect(sent).toHaveLength(1)
expect(sent[0]).toMatchObject({
hook: "session_start",
sessionId: "sess-1",
sessionKey: "discord:chan-9",
runId: "run-7",
agentId: "main",
channel: "discord",
cwd: "/workspace/repo",
model: "openai/gpt-5",
})
})
// A chat turn that never touched a repository genuinely has no workspace. Defaulting to the
// gateway's own directory would attribute the work to wherever the daemon was started.
test("omits the workspace when OpenClaw reports none", async () => {
const sent = captureSends()
const gateway = fakeGateway()
createBeaconPlugin().register(gateway.api)
await gateway.fire("session_start", { sessionId: "sess-1" }, context({ workspaceDir: undefined }))
expect(sent[0]).not.toHaveProperty("cwd")
})
test("reports a model with no provider prefix as its bare id", async () => {
const sent = captureSends()
const gateway = fakeGateway()
createBeaconPlugin().register(gateway.api)
await gateway.fire("session_start", { sessionId: "sess-1" }, context({ modelProviderId: undefined }))
expect(sent[0]?.model).toBe("gpt-5")
})
// The reason the hook event is nested rather than spread: `params` keys belong to the model.
test("a tool argument cannot overwrite the envelope's identity", async () => {
const sent = captureSends()
const gateway = fakeGateway()
createBeaconPlugin().register(gateway.api)
await gateway.fire(
"after_tool_call",
{
toolName: "exec",
toolCallId: "call-1",
params: { command: "echo hi", sessionId: "attacker", cwd: "/etc", hook: "session_end" },
},
context(),
)
expect(sent[0]?.sessionId).toBe("sess-1")
expect(sent[0]?.cwd).toBe("/workspace/repo")
expect(sent[0]?.hook).toBe("after_tool_call")
expect((sent[0]?.event as Record<string, unknown>).params).toMatchObject({ command: "echo hi" })
})
// OpenClaw registers before_tool_call fail-closed: a handler that throws or exceeds its timeout
// blocks the tool call. This handler must therefore never hand OpenClaw something to wait on.
test("before_tool_call returns synchronously without a promise", () => {
captureSends()
const gateway = fakeGateway()
createBeaconPlugin().register(gateway.api)
const returned = gateway.fireSync(
"before_tool_call",
{ toolName: "exec", toolCallId: "call-1", params: { command: "ls" } },
context(),
)
expect(returned).toBeUndefined()
})
// Every observe handler must resolve to undefined: OpenClaw reads a returned object on its
// modify-kind hooks as a request to change behavior.
test("observe handlers resolve to undefined", async () => {
captureSends()
const gateway = fakeGateway()
createBeaconPlugin().register(gateway.api)
for (const hook of ["session_start", "after_tool_call", "llm_output", "message_received"]) {
expect(await gateway.fire(hook, {}, context())).toBeUndefined()
}
})
// apply_patch takes one opaque patch string, so without the paths carried forward from the
// proposal a completed patch produces no file rows at all.
test("carries derivedPaths forward from before_tool_call to after_tool_call", async () => {
const sent = captureSends()
const gateway = fakeGateway()
createBeaconPlugin().register(gateway.api)
await gateway.fire(
"before_tool_call",
{
toolName: "apply_patch",
toolCallId: "call-42",
params: { input: "*** Begin Patch\n*** End Patch\n" },
derivedPaths: ["/workspace/repo/a.go", "/workspace/repo/b.go"],
},
context(),
)
await gateway.fire(
"after_tool_call",
{ toolName: "apply_patch", toolCallId: "call-42", params: { input: "*** Begin Patch\n*** End Patch\n" } },
context(),
)
const completion = sent.at(-1)?.event as Record<string, unknown>
expect(completion.derivedPaths).toEqual(["/workspace/repo/a.go", "/workspace/repo/b.go"])
})
// A patch event enriched with another call's paths would read as evidence that those files
// changed. Absent is the only safe answer.
test("does not attach paths from a different tool call", async () => {
const sent = captureSends()
const gateway = fakeGateway()
createBeaconPlugin().register(gateway.api)
await gateway.fire(
"before_tool_call",
{ toolName: "apply_patch", toolCallId: "call-1", params: {}, derivedPaths: ["/a.go"] },
context(),
)
await gateway.fire("after_tool_call", { toolName: "apply_patch", toolCallId: "call-2", params: {} }, context())
const completion = sent.at(-1)?.event as Record<string, unknown>
expect(completion.derivedPaths).toBeUndefined()
})
// The paths are consumed by the completion they belong to, so a second completion for the same
// id cannot pick them up again.
test("forgets derivedPaths once their call completes", async () => {
const sent = captureSends()
const gateway = fakeGateway()
createBeaconPlugin().register(gateway.api)
await gateway.fire(
"before_tool_call",
{ toolName: "apply_patch", toolCallId: "call-1", params: {}, derivedPaths: ["/a.go"] },
context(),
)
await gateway.fire("after_tool_call", { toolName: "apply_patch", toolCallId: "call-1", params: {} }, context())
await gateway.fire("after_tool_call", { toolName: "apply_patch", toolCallId: "call-1", params: {} }, context())
expect((sent.at(-2)?.event as Record<string, unknown>).derivedPaths).toEqual(["/a.go"])
expect((sent.at(-1)?.event as Record<string, unknown>).derivedPaths).toBeUndefined()
})
// The bug this guards: a gateway serves many conversations in one process, so clearing pending
// paths on `session_end` discards the in-flight apply_patch of every *other* conversation, and
// their completions are then recorded with no file rows. Compaction also ends a session, so it
// would fire in ordinary operation rather than only at shutdown.
test("a session ending does not discard another conversation's in-flight paths", async () => {
const sent = captureSends()
const gateway = fakeGateway()
createBeaconPlugin().register(gateway.api)
const conversationA = context({ sessionId: "sess-a", sessionKey: "discord:a" })
const conversationB = context({ sessionId: "sess-b", sessionKey: "slack:b" })
await gateway.fire(
"before_tool_call",
{ toolName: "apply_patch", toolCallId: "call-a", params: {}, derivedPaths: ["/repo/a.go"] },
conversationA,
)
// Conversation B ends -- by compaction, a reset, an idle timeout, anything.
await gateway.fire("session_end", { sessionId: "sess-b", reason: "compaction" }, conversationB)
await gateway.fire(
"after_tool_call",
{ toolName: "apply_patch", toolCallId: "call-a", params: {} },
conversationA,
)
const completion = sent.at(-1)?.event as Record<string, unknown>
expect(completion.derivedPaths).toEqual(["/repo/a.go"])
})
// Two plugin instances must not share in-flight state.
test("pending paths are scoped to the plugin instance", async () => {
const sent = captureSends()
const first = fakeGateway()
const second = fakeGateway()
createBeaconPlugin().register(first.api)
createBeaconPlugin().register(second.api)
await first.fire(
"before_tool_call",
{ toolName: "apply_patch", toolCallId: "call-x", params: {}, derivedPaths: ["/repo/x.go"] },
context(),
)
await second.fire("after_tool_call", { toolName: "apply_patch", toolCallId: "call-x", params: {} }, context())
expect((sent.at(-1)?.event as Record<string, unknown>).derivedPaths).toBeUndefined()
})
// An event that names its own session is more specific than the handler context, which is the
// gateway's more general answer.
test("an event's own session identity wins over the context's", async () => {
const sent = captureSends()
const gateway = fakeGateway()
createBeaconPlugin().register(gateway.api)
await gateway.fire("session_end", { sessionId: "sess-9", reason: "idle" }, context())
expect(sent[0]?.sessionId).toBe("sess-9")
})
// A payload carrying a cycle, a bigint, or an AbortSignal must not cost the whole event.
test("serializes payloads that JSON.stringify would reject", async () => {
const sent = captureSends()
const gateway = fakeGateway()
createBeaconPlugin().register(gateway.api)
const cyclic: Record<string, unknown> = { toolName: "exec", params: { command: "ls" } }
cyclic.self = cyclic
await gateway.fire("after_tool_call", cyclic, {
...context(),
abortSignal: new AbortController().signal,
tokens: 10n,
})
const event = sent[0]?.event as Record<string, unknown>
expect(event.toolName).toBe("exec")
expect(event.self).toBeUndefined()
expect(() => JSON.stringify(sent[0])).not.toThrow()
})
// A handler that throws on before_tool_call blocks the tool call, so nothing in this plugin may
// propagate an error -- not even a sender that fails outright.
test("a failing sender never reaches the gateway", async () => {
;(globalThis as Record<symbol, unknown>)[senderKey] = () => {
throw new Error("sender exploded")
}
const gateway = fakeGateway()
createBeaconPlugin().register(gateway.api)
expect(() =>
gateway.fireSync("before_tool_call", { toolName: "exec", params: {} }, context()),
).not.toThrow()
await expect(gateway.fire("session_start", { sessionId: "sess-1" }, context())).resolves.toBeUndefined()
})
})