@checkstack/backend 0.10.3 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # @checkstack/backend
 
+## 0.11.0
+
+### Minor Changes
+
+- 6d52276: feat(automation): expose `trigger.actor` so automations can filter on who/what caused an event
+
+  Every platform event now carries an **actor** - the user, application (API
+  client), service (backend-to-backend), or `system` (background /
+  unauthenticated) that caused it - and the automation engine surfaces it to
+  automations as `trigger.actor`. This lets a trigger filter gate on the
+  origin of the event it reacts to:
+
+  ```text
+  {{ trigger.actor.type == "system" }}      # auto-created by the platform
+  {{ trigger.actor.type == "user" }}         # a human
+  {{ trigger.actor.id == "app-deploybot" }}  # a specific application
+  ```
+
+  `trigger.actor` is available on **every** trigger - it is injected by the
+  platform, not declared per trigger - and editor autocomplete + Run Script
+  context types include `trigger.actor.{type,id,name}`.
+
+  How it works:
+
+  - **`@checkstack/common`** adds the canonical `Actor` type / `ActorSchema`
+    and `SYSTEM_ACTOR`.
+  - **`@checkstack/backend-api`** adds `resolveActor(user)` and a
+    `HookEventMeta` envelope. The hook listener / `onHook` signature gains an
+    optional second `meta` argument (additive, backward compatible).
+  - **`@checkstack/backend`** wraps emitted hooks in an envelope so the actor
+    travels with the payload through the distributed queue, unwrapping it
+    before delivery. The RPC emit path captures the authenticated caller;
+    background emits default to the system actor. Raw/legacy queue data is
+    treated as a system-actor payload, so delivery stays backward compatible.
+  - **`@checkstack/automation-backend`** threads the actor into the dispatch
+    scope (`trigger.actor`), available to trigger filters, top-level
+    conditions, and all run templates, and persisted in the run's scope
+    snapshot. Manual runs are attributed to the invoking user.
+  - **`@checkstack/automation-common`** / **`@checkstack/automation-frontend`**
+    expose `trigger.actor` in the editor variable scope and the generated
+    Run Script `context.trigger.actor` types.
+
+  No database migration and no per-trigger schema changes: the actor rides as
+  event-envelope metadata and in the run scope snapshot.
+
+### Patch Changes
+
+- Updated dependencies [6d52276]
+- Updated dependencies [35bc682]
+  - @checkstack/common@0.12.0
+  - @checkstack/backend-api@0.18.0
+  - @checkstack/api-docs-common@0.1.15
+  - @checkstack/auth-common@0.7.2
+  - @checkstack/pluginmanager-common@0.2.4
+  - @checkstack/signal-backend@0.2.10
+  - @checkstack/signal-common@0.2.5
+  - @checkstack/cache-api@0.3.6
+  - @checkstack/queue-api@0.3.6
+
+## 0.10.4
+
+### Patch Changes
+
+- @checkstack/backend-api@0.17.1
+- @checkstack/cache-api@0.3.5
+- @checkstack/queue-api@0.3.5
+- @checkstack/signal-backend@0.2.9
+
 ## 0.10.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "license": "Elastic-2.0",
   "checkstack": {
     "type": "backend"
@@ -14,16 +14,16 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/api-docs-common": "0.1.13",
-    "@checkstack/auth-common": "0.7.0",
-    "@checkstack/backend-api": "0.16.0",
-    "@checkstack/common": "0.10.0",
+    "@checkstack/api-docs-common": "0.1.14",
+    "@checkstack/auth-common": "0.7.1",
+    "@checkstack/backend-api": "0.17.1",
+    "@checkstack/common": "0.11.0",
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/cache-api": "0.3.3",
-    "@checkstack/queue-api": "0.3.3",
-    "@checkstack/signal-backend": "0.2.7",
-    "@checkstack/signal-common": "0.2.3",
-    "@checkstack/pluginmanager-common": "0.2.2",
+    "@checkstack/cache-api": "0.3.5",
+    "@checkstack/queue-api": "0.3.5",
+    "@checkstack/signal-backend": "0.2.9",
+    "@checkstack/signal-common": "0.2.4",
+    "@checkstack/pluginmanager-common": "0.2.3",
     "@hono/zod-validator": "^0.7.6",
     "@orpc/client": "^1.13.14",
     "@orpc/contract": "^1.13.14",
@@ -45,8 +45,8 @@
     "@types/bun": "latest",
     "@types/semver": "^7.5.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.2",
-    "@checkstack/test-utils-backend": "0.1.28",
+    "@checkstack/scripts": "0.3.3",
+    "@checkstack/test-utils-backend": "0.1.30",
     "drizzle-kit": "^0.31.10"
   }
 }

package/src/plugin-manager/api-router.ts

@@ -10,6 +10,7 @@ import {
   Fetch,
   HealthCheckRegistry,
   CollectorRegistry,
+  resolveActor,
   type EmitHookFn,
   type Hook,
 } from "@checkstack/backend-api";
@@ -126,7 +127,12 @@ async function resolveRequestContext({
   const user = await (auth as AuthService).authenticate(c.req.raw);
 
   const emitHook: EmitHookFn = async <T>(hook: Hook<T>, payload: T) => {
-    await (eventBus as EventBus).emit(hook, payload);
+    // Capture the authenticated caller as the event actor so automations can
+    // filter on who/what caused the event (falls back to the system actor for
+    // unauthenticated callers).
+    await (eventBus as EventBus).emit(hook, payload, {
+      actor: resolveActor(user),
+    });
   };
 
   const pluginMetadata: PluginMetadata | undefined =

package/src/services/event-bus.test.ts

@@ -3,6 +3,7 @@ import { EventBus } from "./event-bus";
 import type { QueueManager } from "@checkstack/queue-api";
 import type { Logger, Hook } from "@checkstack/backend-api";
 import { createHook } from "@checkstack/backend-api";
+import { SYSTEM_ACTOR } from "@checkstack/common";
 import {
   createMockLogger,
   createMockQueueManager,
@@ -272,6 +273,63 @@ describe("EventBus", () => {
     });
   });
 
+  describe("Actor metadata", () => {
+    it("delivers the system actor by default when no meta is provided", async () => {
+      const testHook = createHook<{ value: number }>("test.actor.hook");
+      let receivedActor: unknown;
+
+      await eventBus.subscribe("plugin-1", testHook, async (_payload, meta) => {
+        receivedActor = meta?.actor;
+      });
+
+      await eventBus.emit(testHook, { value: 1 });
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      expect(receivedActor).toEqual(SYSTEM_ACTOR);
+    });
+
+    it("delivers the provided actor alongside the payload", async () => {
+      const testHook = createHook<{ value: number }>("test.actor.hook");
+      let received: { value: number } | undefined;
+      let receivedActor: unknown;
+
+      await eventBus.subscribe("plugin-1", testHook, async (payload, meta) => {
+        received = payload;
+        receivedActor = meta?.actor;
+      });
+
+      const actor = { type: "user", id: "user-1", name: "Nico" } as const;
+      await eventBus.emit(testHook, { value: 7 }, { actor });
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      expect(received).toEqual({ value: 7 });
+      expect(receivedActor).toEqual(actor);
+    });
+
+    it("delivers actor meta on instance-local emit", async () => {
+      const testHook = createHook<{ value: number }>("test.actor.local");
+      let receivedActor: unknown;
+
+      await eventBus.subscribe(
+        "plugin-1",
+        testHook,
+        async (_payload, meta) => {
+          receivedActor = meta?.actor;
+        },
+        { mode: "instance-local" },
+      );
+
+      const actor = {
+        type: "application",
+        id: "app-deploybot",
+        name: "Deploy Bot",
+      } as const;
+      await eventBus.emitLocal(testHook, { value: 1 }, { actor });
+
+      expect(receivedActor).toEqual(actor);
+    });
+  });
+
   describe("Shutdown", () => {
     it("should stop all queue channels", async () => {
       const hook1 = createHook<{ test: string }>("hook1");

package/src/services/event-bus.ts

@@ -1,13 +1,55 @@
 import type { Queue, QueueManager } from "@checkstack/queue-api";
 import type {
   Hook,
+  HookEventMeta,
   HookSubscribeOptions,
   HookUnsubscribe,
   Logger,
 } from "@checkstack/backend-api";
 import type { EventBus as IEventBus } from "@checkstack/backend-api";
+import { SYSTEM_ACTOR } from "@checkstack/common";
 
-export type HookListener<T> = (payload: T) => Promise<void>;
+export type HookListener<T> = (
+  payload: T,
+  meta?: HookEventMeta,
+) => Promise<void>;
+
+/**
+ * Internal queue envelope. Hooks are enqueued wrapped so event metadata (the
+ * acting `actor`) rides alongside the typed payload through the distributed
+ * queue. `invokeListener` unwraps it before calling listeners, so subscribers
+ * still receive the payload as their first argument (plus optional `meta`).
+ */
+const HOOK_ENVELOPE_MARKER = "__checkstackHookEnvelope" as const;
+
+interface HookEnvelope<T> {
+  [HOOK_ENVELOPE_MARKER]: 1;
+  payload: T;
+  meta: HookEventMeta;
+}
+
+function isHookEnvelope(data: unknown): data is HookEnvelope<unknown> {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    (data as Record<string, unknown>)[HOOK_ENVELOPE_MARKER] === 1
+  );
+}
+
+/**
+ * Unwrap queued hook data into `{ payload, meta }`. Data emitted before the
+ * envelope existed (or enqueued by other producers) is treated as a raw
+ * payload with the system actor, so delivery stays backward compatible.
+ */
+function unwrapHookData(data: unknown): {
+  payload: unknown;
+  meta: HookEventMeta;
+} {
+  if (isHookEnvelope(data)) {
+    return { payload: data.payload, meta: data.meta };
+  }
+  return { payload: data, meta: { actor: SYSTEM_ACTOR } };
+}
 
 interface ListenerRegistration {
   id: string;
@@ -201,7 +243,11 @@ export class EventBus implements IEventBus {
    * need cross-process delivery must therefore ensure at least one
    * listener registers on every replica that should receive the hook.
    */
-  async emit<T>(hook: Hook<T>, payload: T): Promise<void> {
+  async emit<T>(
+    hook: Hook<T>,
+    payload: T,
+    meta?: HookEventMeta,
+  ): Promise<void> {
     const hasDistributedListeners =
       (this.listeners.get(hook.id)?.length ?? 0) > 0;
     const hasLocalListeners =
@@ -218,11 +264,18 @@ export class EventBus implements IEventBus {
 
     // Create channel lazily if not exists
     if (!channel) {
-      channel = this.queueManager.getQueue<T>(hook.id);
+      channel = this.queueManager.getQueue<unknown>(hook.id);
       this.queueChannels.set(hook.id, channel);
     }
 
-    await channel.enqueue(payload);
+    // Enqueue the payload wrapped in an envelope so the acting actor (defaulting
+    // to the system actor for background/unauthenticated emits) travels with it.
+    const envelope: HookEnvelope<T> = {
+      [HOOK_ENVELOPE_MARKER]: 1,
+      payload,
+      meta: meta ?? { actor: SYSTEM_ACTOR },
+    };
+    await channel.enqueue(envelope);
     this.logger.debug(`Emitted hook: ${hook.id}`);
   }
 
@@ -231,7 +284,11 @@ export class EventBus implements IEventBus {
    * Use this for instance-local hooks like pluginDeregistering.
    * Uses Promise.allSettled to ensure one listener error doesn't block others.
    */
-  async emitLocal<T>(hook: Hook<T>, payload: T): Promise<void> {
+  async emitLocal<T>(
+    hook: Hook<T>,
+    payload: T,
+    meta?: HookEventMeta,
+  ): Promise<void> {
     const registrations = this.localListeners.get(hook.id) || [];
 
     if (registrations.length === 0) {
@@ -239,10 +296,13 @@ export class EventBus implements IEventBus {
       return;
     }
 
+    // Local hooks bypass the queue, so deliver `meta` straight to listeners
+    // (defaulting to the system actor when none was provided).
+    const resolvedMeta: HookEventMeta = meta ?? { actor: SYSTEM_ACTOR };
     const results = await Promise.allSettled(
       registrations.map(async (reg) => {
         try {
-          await reg.listener(payload);
+          await reg.listener(payload, resolvedMeta);
           this.logger.debug(
             `Local listener ${reg.id} (${reg.pluginId}) processed successfully`
           );
@@ -315,10 +375,11 @@ export class EventBus implements IEventBus {
    */
   private async invokeListener(
     registration: ListenerRegistration,
-    payload: unknown
+    data: unknown
   ): Promise<void> {
+    const { payload, meta } = unwrapHookData(data);
     try {
-      await registration.listener(payload);
+      await registration.listener(payload, meta);
       this.logger.debug(
         `Listener ${registration.id} (${registration.consumerGroup}) processed successfully`
       );