Pass immutable hook target identifiers to enable()

Author: ndisidore

.agents/skills/write-gatekeeper/SKELETON.md

@@ -13,6 +13,7 @@ import {
   Gatekeeper,
   HookController,        // Remove if no hooks
   HookInitiator,         // Remove if no hooks
+  HookTargetMetadata,    // Remove if no hooks
   ResourceDescription,
   ApprovalQueue,
   ObservationDescription,
@@ -337,8 +338,9 @@ class MyConfiguratorUI extends RpcTarget {
 }
 
 // ---------------------------------------------------------------------------
-// Hook type — remove this section (and HookController/HookInitiator imports, the `subscribe`
-// method, the `hookTsType` field, and MyHookControllerImpl) if the gatekeeper doesn't push events.
+// Hook type — remove this section (and the HookController/HookInitiator/HookTargetMetadata
+// imports, the `subscribe` method, the `hookTsType` field, and MyHookControllerImpl) if the
+// gatekeeper doesn't push events.
 //
 // The hook interface from types.d.ts is implemented by the Gadget as an RpcTarget. Intersect it
 // with RpcTarget so it satisfies the HookController/HookInitiator generic constraints (Hook
@@ -443,7 +445,11 @@ export class MyHookControllerImpl extends WorkerEntrypoint<Env, MyHookController
   // Called when the user enables the hook. Store `initiator` somewhere it can be reached when an
   // event arrives — typically an event-source DO. Don't store other state until now; everything
   // else is already in `this.ctx.props`. If already enabled, replace the previous initiator.
-  async enable(initiator: Fetcher<HookInitiator<MyHook>>): Promise<void> {
+  //
+  // `target` identifies where the hook delivers (workspace, and gadget when pinned to one). Store
+  // it too if you display or link to the target; otherwise ignore it, but keep the parameter
+  // declared — RPC argument validation rejects arguments the receiver doesn't declare.
+  async enable(initiator: Fetcher<HookInitiator<MyHook>>, target: HookTargetMetadata): Promise<void> {
     // TODO: persist `initiator` (e.g. forward it to an event-source DO keyed by props).
   }
 

.agents/skills/write-gatekeeper/SKILL.md

@@ -303,7 +303,7 @@ Some services can push events to the Gadget (inbound email, webhooks, chat messa
 ### Lifecycle
 
 1. **Register.** The Gadget calls your Session method (e.g. `subscribe(callback, filter)`). Inside it, construct a `HookController` whose `props` capture the specifics of *this* registration, then call `approvalQueue.bindHook(controller, callback, description)`. The overseer stores the callback and records the hook (initially **disabled**). Do **not** store the callback yourself — it is bound to the current session and would be revoked when the session ends.
-2. **Enable.** When the user approves the hook in the Workshop UI, the overseer calls `controller.enable(initiator)`. Store the `initiator` Fetcher somewhere it can be reached when events arrive (e.g. an event-source DO). Avoid storing any other state until enabled; everything else should already be in the controller's `props`.
+2. **Enable.** When the user approves the hook in the Workshop UI, the overseer calls `controller.enable(initiator, target)`. Store the `initiator` Fetcher somewhere it can be reached when events arrive (e.g. an event-source DO). `target` identifies where the hook delivers (workspace, plus gadget when the hook is pinned to one); persist it alongside the initiator if you display or link to the target — the IDs are fixed when the hook is bound, so there is nothing to refresh. A gatekeeper that doesn't need it still has to declare the parameter, since RPC argument validation rejects arguments the receiver doesn't declare. Avoid storing any other state until enabled; everything else should already be in the controller's `props`.
 3. **Deliver.** When the event occurs, call `initiator.startHook()`. This returns `{callback, approvalQueue}` bound to a fresh session. Call `authorizeObservation()` (a hook event is almost always an observation; register actions too if the callback's return value triggers side effects), then invoke the `callback` to deliver the event to the Gadget.
 4. **Disable / delete.** The overseer calls `controller.disable()`. Forget the stored `initiator` and clean up all related state — `disable()` may never be called again, though the overseer may later call `enable()` afresh.
 

packages/gatekeeper-email/src/email.ts

@@ -7,6 +7,7 @@ import {
   Gatekeeper,
   HookController,
   HookInitiator,
+  HookTargetMetadata,
   ResourceDescription,
   ApprovalQueue,
   VendorDescription,
@@ -581,7 +582,10 @@ export class EmailGatekeeperImpl extends DurableObject<Env, EmailGatekeeperImplP
 @validateRpc()
 export class EmailHookControllerImpl extends WorkerEntrypoint<Env, EmailGatekeeperImplProps>
     implements HookController<EmailHookTarget> {
-  async enable(initiator: Fetcher<HookInitiator<EmailHookTarget>>): Promise<void> {
+  // `_target` is unused -- email doesn't display its hooks -- but must be declared, since RPC
+  // argument validation is generated from this signature and would reject the extra argument.
+  async enable(initiator: Fetcher<HookInitiator<EmailHookTarget>>,
+               _target: HookTargetMetadata): Promise<void> {
     return this.#setHook(initiator);
   }
 

packages/workshop-backend/__tests__/overseer-hooks.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
+import { RpcStub as NativeRpcStub } from "cloudflare:workers";
 import { DEFAULT_ADMIN_CONFIG, serializeAdminConfig } from "../src/admin-config.js";
 import { OverseerDurableObject } from "../src/overseer.js";
 
@@ -87,3 +88,63 @@ describe("OverseerDurableObject.startHook", () => {
     await expect(overseer.startHook(1)).rejects.toThrow("Hook has been deleted or disabled.");
   });
 });
+
+async function makeTargetOverseer(gadgetId?: number) {
+  let controllerEnable = vi.fn(async (_initiator: object, _target: object) => {});
+  let record = {
+    id: 4,
+    actionId: 12,
+    gatekeeperId: 1,
+    gadgetId,
+    controller: {enable: controllerEnable},
+    callback: {},
+    description: {title: "Incoming email", description: "Receives email"},
+    enabled: false,
+  };
+  let overseer = {
+    open: OverseerDurableObject.prototype.open,
+    impl: {
+      ownerId: "user-id",
+      ensureAmbientCapsules: async () => {},
+      joinPresence: () => () => {},
+      users: {
+        idFromString: (id: string) => id,
+        get: () => ({
+          whoami: async () => ({id: "profile-id", name: "Test User"}),
+        }),
+      },
+      ctx: {
+        id: {toString: () => "workspace-id"},
+        exports: {GatekeeperHookLoopback: ({props}: {props: object}) => props},
+      },
+      storage: {
+        prohibitAllSharing: {get: () => false},
+        boundHooks: {get: () => record, put: vi.fn()},
+        actions: {get: () => undefined, put: vi.fn()},
+      },
+    },
+  } satisfies Pick<OverseerDurableObject, "open"> & {impl: object};
+  let notifyClosed = new NativeRpcStub<() => void>(() => {});
+  let client = await overseer.open("user-id", "profile-id", notifyClosed);
+  return {client, controllerEnable};
+}
+
+describe("hook target", () => {
+
+  it("passes the workspace and gadget IDs to enable()", async () => {
+    let {client, controllerEnable} = await makeTargetOverseer(17);
+
+    await client.enableHook(4);
+
+    expect(controllerEnable).toHaveBeenCalledTimes(1);
+    expect(controllerEnable.mock.calls[0][1]).toEqual({workspaceId: "workspace-id", gadgetId: 17});
+  });
+
+  it("omits the gadget ID for a hook that is not pinned to one", async () => {
+    let {client, controllerEnable} = await makeTargetOverseer();
+
+    await client.enableHook(4);
+
+    expect(controllerEnable.mock.calls[0][1]).toEqual({workspaceId: "workspace-id"});
+  });
+});

packages/workshop-backend/src/overseer.ts

@@ -7082,7 +7082,11 @@ class OverseerClientInterface extends RpcTarget implements Overseer {
 
       await record.controller.enable(
           this.impl.ctx.exports.GatekeeperHookLoopback({props}) as unknown as
-              Fetcher<HookInitiator<RpcTarget>>);
+              Fetcher<HookInitiator<RpcTarget>>,
+          {
+            workspaceId: this.impl.ctx.id.toString(),
+            ...(record.gadgetId !== undefined ? {gadgetId: record.gadgetId} : {}),
+          });
 
       record.enabled = true;
       this.impl.storage.boundHooks.put(record);

packages/workshop-shared/src/gatekeeper.ts

@@ -1051,14 +1051,34 @@ export type HookDescription = {
   description: string;
 }
 
+// Identifies where a hook delivers its events, for display and navigation by a gatekeeper that
+// surfaces its hooks in a UI. Passed to `HookController.enable()`.
+//
+// Both fields are fixed when the hook is bound, so a gatekeeper may persist them alongside the
+// initiator and never needs to refresh them. They are opaque display/routing identifiers: they
+// must not be used for authorization, identity, or storage scoping.
+export type HookTargetMetadata = {
+  // The workspace the hook delivers into.
+  workspaceId: string;
+
+  // The specific gadget within that workspace, when the hook is pinned to one. Absent means the
+  // workspace's current default gadget.
+  gadgetId?: number;
+}
+
 // Object passed to `ApprovalQueue.bindHook()`, providing the overseer with callbacks to enable
 // or disable a hook.
 export interface HookController<Hook extends RpcTarget> extends WorkerEntrypoint {
   // Called to enable this hook. When a hook event is to be delivered, initiator.startHook() must
   // be called first, before actually invoking the hook.
   //
   // If the hook was already enabled, the previously-registered `initiator` should be replaced.
-  enable(initiator: Fetcher<HookInitiator<Hook>>): Promise<void>;
+  //
+  // `target` identifies where the hook delivers, for gatekeepers that display or link to it. A
+  // gatekeeper that doesn't need it may ignore the value, but must still *declare* the parameter:
+  // RPC argument validation is generated from the declared signature, and a call carrying an
+  // argument the receiver does not declare is rejected.
+  enable(initiator: Fetcher<HookInitiator<Hook>>, target: HookTargetMetadata): Promise<void>;
 
   // Unregister the hook, so that future events stop being delivered. The gatekeeper should forget
   // the `initiator` previously registered by `enable()`.