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 { createBeaconPlugin } from "./beacon"
const senderKey = Symbol.for("beacon.cline.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
}
afterEach(() => {
delete (globalThis as Record<symbol, unknown>)[senderKey]
})
describe("beacon cline plugin", () => {
test("declares itself as a hooks plugin", () => {
const plugin = createBeaconPlugin()
expect(plugin.manifest.capabilities).toEqual(["hooks"])
expect(Object.keys(plugin.hooks).sort()).toEqual(["afterRun", "afterTool", "beforeRun", "beforeTool"])
})
test("forwards each hook with its stage name", async () => {
const sent = captureSends()
const plugin = createBeaconPlugin()
await plugin.hooks.beforeRun({ taskId: "task-1" })
await plugin.hooks.beforeTool({ taskId: "task-1", toolCall: { name: "read_file" } })
await plugin.hooks.afterTool({ taskId: "task-1", toolCall: { name: "read_file" } })
await plugin.hooks.afterRun({ taskId: "task-1" })
expect(sent.map((event) => event.type)).toEqual(["beforeRun", "beforeTool", "afterTool", "afterRun"])
})
// The hook adapter reads these at the top level of the envelope. Leaving them wherever the
// context happened to nest them would cost the session id, which is what groups a task's events.
test("lifts task identity out of nested context shapes", async () => {
const sent = captureSends()
const plugin = createBeaconPlugin()
await plugin.hooks.afterTool({ task: { id: "task-nested" }, workspace_roots: ["/repo"] })
expect(sent[0].taskId).toBe("task-nested")
expect(sent[0].workspaceRoots).toEqual(["/repo"])
})
// The setup context is the only place the workspace identity is guaranteed to appear, so it has
// to reach hooks that did not carry it themselves.
test("carries setup context onto later hooks", async () => {
const sent = captureSends()
const plugin = createBeaconPlugin()
plugin.setup(undefined, { workspaceRoots: ["/repo"], clineVersion: "3.36.0" })
await plugin.hooks.beforeTool({ toolCall: { name: "read_file" } })
expect(sent[0].workspaceRoots).toEqual(["/repo"])
expect(sent[0].clineVersion).toBe("3.36.0")
})
// The shape above is a top-level one. The setup context is reported to nest the workspace under
// an object of its own, and reading only the top level extracted nothing to carry -- costing the
// working directory, repository and branch on every event of the task.
test("carries a nested setup workspace onto later hooks", async () => {
const sent = captureSends()
const plugin = createBeaconPlugin()
plugin.setup(undefined, { workspaceInfo: { rootPath: "/repo" }, clineVersion: "3.36.0" })
await plugin.hooks.afterTool({ toolCall: { name: "read_file" } })
expect(sent[0].cwd).toBe("/repo")
expect(sent[0].clineVersion).toBe("3.36.0")
})
test("reads a nested roots array", async () => {
const sent = captureSends()
const plugin = createBeaconPlugin()
plugin.setup(undefined, { workspace: { roots: ["/repo", "/other"] } })
await plugin.hooks.beforeRun({ taskId: "task-1" })
expect(sent[0].workspaceRoots).toEqual(["/repo", "/other"])
})
// A non-object under a workspace key must not throw: the plugin runs inside the host, and an
// exception here reaches the user as a broken plugin.
test("survives a non-object workspace value", async () => {
const sent = captureSends()
const plugin = createBeaconPlugin()
plugin.setup(undefined, { workspaceInfo: "/repo" })
await expect(plugin.hooks.beforeRun({ taskId: "task-1" })).resolves.toBeUndefined()
expect(sent[0].taskId).toBe("task-1")
})
test("context fields win over the captured setup context", async () => {
const sent = captureSends()
const plugin = createBeaconPlugin()
plugin.setup(undefined, { taskId: "task-setup" })
await plugin.hooks.afterRun({ taskId: "task-current" })
expect(sent[0].taskId).toBe("task-current")
})
// Cline awaits these handlers inside its own run loop. A hook that returns a rejected promise, or
// that throws, is a hook that can break the run it was only supposed to observe.
test("never rejects when the sender throws", async () => {
;(globalThis as Record<symbol, unknown>)[senderKey] = () => {
throw new Error("sender exploded")
}
const plugin = createBeaconPlugin()
await expect(plugin.hooks.beforeTool({ taskId: "task-1" })).resolves.toBeUndefined()
})
test("observes without cancelling: every hook resolves to undefined", async () => {
captureSends()
const plugin = createBeaconPlugin()
for (const hook of Object.values(plugin.hooks)) {
expect(await hook({ taskId: "task-1", toolCall: { name: "execute_command" } })).toBeUndefined()
}
})
// A live SDK context is not plain data. JSON.stringify throws on a cycle, so a payload carrying
// one has to survive as the fields around it rather than being dropped whole.
test("survives a circular context", async () => {
const sent = captureSends()
const plugin = createBeaconPlugin()
const context: Record<string, unknown> = { taskId: "task-cycle" }
context.self = context
await plugin.hooks.afterRun(context)
expect(sent[0].taskId).toBe("task-cycle")
expect(() => JSON.stringify(sent[0])).not.toThrow()
})
})