New hooks based on persistent stubs

Author: kentonv

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

@@ -10,7 +10,8 @@ import {
   GatekeeperUser,
   GatekeeperVendor as GatekeeperVendorIface,
   Gatekeeper,
-  HookInitiator,
+  HookController,        // Remove if no hooks
+  HookInitiator,         // Remove if no hooks
   ResourceDescription,
   ApprovalQueue,
   VendorDescription,
@@ -295,11 +296,17 @@ class MyConfiguratorUI extends RpcTarget {
 }
 
 // ---------------------------------------------------------------------------
-// Hook type — remove this section if the gatekeeper doesn't support hooks.
-// Intersect the hook interface from types.d.ts with WorkerEntrypoint so it satisfies the
-// Gatekeeper generic constraint (Hook extends WorkerEntrypoint).
-
-type MyHook = WorkerEntrypoint & MyHookIface;
+// Hook type — remove this section (and HookController/HookInitiator 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
+// extends RpcTarget).
+//
+// Note that you can also use a plain function as a hook type, e.g. `RpcStub<() => Promise<void>>`.
+// In that case you would not need to merge the type with `RpcTarget`.
+
+type MyHook = RpcTarget & MyHookIface;
 
 // ---------------------------------------------------------------------------
 // GatekeeperImpl DO — per-resource instance, runs as a facet of the Overseer
@@ -310,7 +317,7 @@ type MyGatekeeperImplProps = {
 };
 
 export class MyGatekeeperImpl extends DurableObject<Env, MyGatekeeperImplProps>
-    implements Gatekeeper<MySession, MyHook> {
+    implements Gatekeeper<MySession> {
 
   async describe(): Promise<ResourceDescription> {
     return {
@@ -330,6 +337,7 @@ export class MyGatekeeperImpl extends DurableObject<Env, MyGatekeeperImplProps>
   async startSession(approvalQueue: RpcStub<ApprovalQueue>): Promise<MySession> {
     return new MySessionImpl(
       approvalQueue.dup(),  // Always dup() before storing
+      this.ctx,
       // ... API client, props, etc.
     );
   }
@@ -351,24 +359,77 @@ export class MyGatekeeperImpl extends DurableObject<Env, MyGatekeeperImplProps>
     // TODO: Undo the action (look up what was done from own storage)
     throw new Error("Revert not implemented");
   }
+}
+
+// ---------------------------------------------------------------------------
+// HookController — remove if the gatekeeper doesn't push events.
+//
+// A WorkerEntrypoint the overseer uses to enable/disable the hook after the user approves it.
+// It is constructed with `props` carrying the specifics of that particular registration, so it
+// needs no other state. If your gatekeeper offers several kinds of hooks, give each its own
+// controller class.
+
+// Bind-time details for a single hook registration, baked into the controller's props.
+type MyHookProps = {
+  // TODO: e.g. an event kind, a filter, a sub-resource id, etc. — whatever the registration
+  // method received and the controller/event source will need later.
+  filter?: string;
+};
+
+type MyHookControllerImplProps = MyGatekeeperImplProps & MyHookProps;
+
+export class MyHookControllerImpl extends WorkerEntrypoint<Env, MyHookControllerImplProps>
+    implements HookController<MyHook> {
+  // 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> {
+    // TODO: persist `initiator` (e.g. forward it to an event-source DO keyed by props).
+  }
 
-  async setHook(hook: Fetcher<HookInitiator<MyHook>> | null): Promise<void> {
-    // Remove the Hook type parameter from Gatekeeper<> above if hooks are not supported.
-    // If hooks are supported, store the HookInitiator Fetcher and call its startHook()
-    // method when an event arrives. startHook() returns {hook, approvalQueue} -- use the
-    // approvalQueue to register observations/actions, then call methods on the hook.
+  // Called when the hook is disabled or deleted. Forget the stored initiator and clean up all
+  // related state. May never be called again, though the overseer may later call enable() afresh.
+  async disable(): Promise<void> {
+    // TODO: forget the stored initiator.
   }
 }
 
+// Event delivery (sketch). When the external event arrives — e.g. in the event-source DO that
+// holds the `initiator` — invoke the hook like so:
+//
+//   async onEvent(initiator: Fetcher<HookInitiator<MyHook>>, event: MyEvent) {
+//     // startHook() begins a fresh session and returns the callback (re-bound to it) plus an
+//     // ApprovalQueue. `using` disposes the result (and its stubs) at end of scope.
+//     using result = initiator.startHook();
+//
+//     // A hook event is almost always an observation. (Register actions too if invoking the
+//     // callback can cause side effects.) Pipeline through the not-yet-resolved promise.
+//     await result.approvalQueue.authorizeObservation({
+//       title: "TODO: short event summary",
+//       description: "TODO: details about the event being delivered",
+//     });
+//
+//     // Deliver the event to the Gadget's callback.
+//     await result.callback.onMyEvent(event);
+//   }
+
 // ---------------------------------------------------------------------------
 // SessionImpl — the RPC interface exposed to the Gadget
 
 class MySessionImpl extends RpcTarget implements MySession {
-  #approvalQueue: ApprovalQueue;
+  #approvalQueue: RpcStub<ApprovalQueue>;
+  #ctx: DurableObjectState<MyGatekeeperImplProps>;
 
-  constructor(approvalQueue: ApprovalQueue) {
+  constructor(
+      approvalQueue: RpcStub<ApprovalQueue>,
+      ctx: DurableObjectState<MyGatekeeperImplProps>) {
     super();
     this.#approvalQueue = approvalQueue;
+    this.#ctx = ctx;
+  }
+
+  [Symbol.dispose]() {
+    this.#approvalQueue[Symbol.dispose]();
   }
 
   // Example: observation (read). Fetch data, then authorize before returning.
@@ -397,6 +458,22 @@ class MySessionImpl extends RpcTarget implements MySession {
 
     // TODO: Update cache/simulation state so subsequent reads reflect this
   }
+
+  // Example: hook registration — remove if the gatekeeper doesn't push events.
+  // `callback` is a persistent stub the Gadget created with ctx.restore(). Construct a controller
+  // whose props capture the specifics of THIS registration (e.g. `filter`), then hand it, the
+  // callback, and a user-facing description to the overseer via bindHook(). For multiple hook
+  // kinds, pick the appropriate controller class here. Do NOT store the callback yourself — it is
+  // bound to this session and would be revoked when the session ends.
+  async subscribe(callback: RpcStub<MyHook>, filter?: string): Promise<void> {
+    let controller = this.#ctx.exports.MyHookControllerImpl({
+      props: { ...this.#ctx.props, filter },
+    });
+    await this.#approvalQueue.bindHook(controller, callback, {
+      title: "TODO: short hook title",
+      description: `TODO: what events this hook delivers${filter ? ` (filter: ${filter})` : ""}`,
+    });
+  }
 }
 ```
 
@@ -417,6 +494,8 @@ class MySessionImpl extends RpcTarget implements MySession {
 }
 ```
 
+Only Durable Object classes go in `new_sqlite_classes`. `MyHookControllerImpl` is a `WorkerEntrypoint`, so it needs no migration entry — but, like all entrypoints, it must be `export`ed from the worker's main module. If your hook uses a dedicated event-source DO to hold the `initiator`, add that DO here too.
+
 ## Creating the `types.txt` symlink
 
 ```bash

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

@@ -9,7 +9,7 @@ A Gatekeeper is a Cloudflare Worker that mediates all access between a Gadget an
 
 - **Vendor** (`GatekeeperVendor`, a `WorkerEntrypoint`) — top-level entry for the service. One per service.
 - **User** (`GatekeeperUser`, a `WorkerEntrypoint` with `ctx.props`) — a human user's authenticated connection.
-- **Instance** (`Gatekeeper<Session, Hook>`, a DO facet of the Overseer) — per-resource, per-Gadget binding that provides the Session API.
+- **Instance** (`Gatekeeper<Session>`, a DO facet of the Overseer) — per-resource, per-Gadget binding that provides the Session API.
 
 Read `packages/workshop-shared/src/gatekeeper.ts` for the canonical interfaces and detailed JSDoc.
 
@@ -40,7 +40,7 @@ Study the service's API docs. Identify:
 
 ### Step 2: Design the Session types
 
-Create `src/types.d.ts` defining the Session interface (and Hook interface if the service pushes events).
+Create `src/types.d.ts` defining the Session interface (and Hook interface if the service pushes events — see [Hooks](#hooks-push-notifications)).
 
 Before designing, read `packages/workshop-shared/node_modules/capnweb/README.md` to understand what Cap'n Web RPC supports — this determines what types and patterns are expressible in the Session interface.
 
@@ -175,6 +175,32 @@ Keep in mind that the agent calling the API (or the agent writing a gadget to ca
 
 For concrete examples, see the Google gatekeeper's Google Docs simulation/cache handling and BigQuery dry-run scope enforcement.
 
+## Hooks (push notifications)
+
+Some services can push events to the Gadget (inbound email, webhooks, chat messages, etc.). A gatekeeper exposes this as a **hook**: the Gadget registers a callback, and the gatekeeper later invokes it when an event arrives. Hooks are persistent — they survive across sessions and server restarts — and are subject to the same observation/action approval model as everything else.
+
+`gatekeeper-email` is the canonical reference implementation. Read it alongside the `HookController`, `HookInitiator`, and `ApprovalQueue.bindHook()` JSDoc in `gatekeeper.ts`.
+
+### The pieces
+
+- **Hook interface** (in `types.d.ts`): the methods the Gadget implements to receive events, e.g. `EmailHook.receiveEmail(email)`. It is implemented by the Gadget as an **`RpcTarget`** (or a plain function), *not* a `WorkerEntrypoint`. Reference it from `describe()` via `hookTsType`.
+- **Session method**: a method like `subscribe(callback)` that the Gadget (or, more commonly, an agent in a one-off `executeCode` call) uses to register interest. The `callback` is a **persistent stub** (created by the Gadget with `ctx.restore()`), so it can be stored and re-invoked long after the session ends.
+- **`HookController`** (a `WorkerEntrypoint` you implement): lets the overseer `enable()` / `disable()` the hook. All the state it needs must live in its `props`, so it is constructed via `this.ctx.exports.MyHookControllerImpl({props})` **at bind time**, immediately before calling `bindHook()` — see below.
+- **`HookInitiator`** (provided to you by the overseer): you call `startHook()` on it when an event arrives.
+
+### 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`.
+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.
+
+Because the callback is a persistent stub tied to a session, the gatekeeper never stores it directly; the overseer hands it back (re-bound to a new session) each time you call `startHook()`. See the SKELETON for the full code shape.
+
+### Documentation
+
+When defining a session interface with hooks, it's important to include comments that clearly state when a method expects to be passed a *persistent* stub created with `ctx.restore()`, as opposed to a regular RpcStub. The caller needs to do extra work to make sure the stub they provide you is persistent.
+
 ## Tips
 
 - `types.txt` must be a **symlink** to `types.d.ts`, never a copy.

package.json

@@ -18,6 +18,6 @@
     "jsonc-parser": "^3.3.1",
     "oxlint": "^1.71.0",
     "typescript": "^5.9.3",
-    "wrangler": "^4.92.0"
+    "wrangler": "^4.103.0"
   }
 }

packages/gatekeeper-cloudflare/package.json

@@ -17,6 +17,6 @@
   },
   "devDependencies": {
     "typescript": "^5.9.3",
-    "wrangler": "^4.92.0"
+    "wrangler": "^4.103.0"
   }
 }