@frockbot/plugin-routines 0.3.45 → 0.3.47

package/src/client/index.ts

@@ -1,3 +1,4 @@
+import { decodeConnectionTriggerCatalogV1 } from "@frockbot/connection-core";
 /// <reference path="../env.d.ts" />
 
 // The Routines hosted client Contribution.
@@ -88,6 +89,23 @@ export const routinesClientPlugin: ClientPlugin = (ctx) => {
         state.value.routines = view.routines;
         state.value.loaded = true;
         state.value.error = undefined;
+        try {
+          const catalog = decodeConnectionTriggerCatalogV1(
+            await request(
+              `/api/bots/${encodeURIComponent(botId)}/routines/triggers`,
+            ),
+          );
+          if (state.value.botId === botId) {
+            state.value.triggers = catalog.items;
+            state.value.triggerError = undefined;
+          }
+        } catch {
+          if (state.value.botId === botId) {
+            state.value.triggers = [];
+            state.value.triggerError =
+              "Events are temporarily unavailable. Try again shortly.";
+          }
+        }
       } catch (error) {
         state.value.error = message(error, "Could not load Routines");
       }

package/src/client/state.ts

@@ -1,3 +1,4 @@
+import type { ConnectionTriggerTypeV1 } from "@frockbot/connection-core";
 import type { InjectionKey, Ref } from "vue";
 import type {
   RoutineHookMintV1,
@@ -22,6 +23,8 @@ export interface RoutinesClientState {
   /** The Bot the loaded Routines belong to; nothing is shown for another. */
   botId?: string;
   routines: RoutineViewV1[];
+  triggers?: ConnectionTriggerTypeV1[];
+  triggerError?: string;
   /** Run logs by Routine, loaded on demand when a log is opened. */
   runs: Record<string, RoutineRunEntryViewV1[]>;
   /**

package/src/records.ts

@@ -1,3 +1,7 @@
+import {
+  decodeConnectionTriggerV1,
+  type ConnectionTriggerV1,
+} from "@frockbot/connection-core";
 // The durable Routine records, and their strict codecs.
 //
 // Every record is versioned, exact-field, and decoded at the seam it crosses.
@@ -46,9 +50,8 @@ export type RoutineWriterV1 =
   | { kind: "bot"; botId: string; sessionId: string; turnId: string };
 
 /** A Routine that fires on a delivered event rather than on a clock. */
-export interface RoutineTriggerV1 {
-  kind: "webhook";
-}
+export type RoutineTriggerV1 =
+  { kind: "webhook" } | ({ kind: "connection" } & ConnectionTriggerV1);
 
 /**
  * One Routine. `schedule` and `trigger` are exclusive: "never both `schedule`
@@ -178,10 +181,32 @@ export function decodeRoutineTriggerV1(
   label = "Routine trigger",
 ): RoutineTriggerV1 {
   const candidate = record(value, label);
+  if (candidate.kind === "connection") {
+    routineExactKeys(
+      candidate,
+      ["kind", "connectionId", "triggerType", "config"],
+      [],
+      label,
+    );
+    try {
+      return {
+        kind: "connection",
+        ...decodeConnectionTriggerV1({
+          connectionId: candidate.connectionId,
+          triggerType: candidate.triggerType,
+          config: candidate.config,
+        }),
+      };
+    } catch {
+      throw new RoutineDecodeError(
+        "Choose an available event from an existing connection",
+      );
+    }
+  }
   routineExactKeys(candidate, ["kind"], [], label);
   if (candidate.kind !== "webhook") {
     throw new RoutineDecodeError(
-      `${label} kind must be "webhook"; no other delivery ships yet`,
+      `${label} kind must be "webhook" or "connection"`,
     );
   }
   return { kind: "webhook" };

package/src/scheduler.ts

@@ -1,3 +1,4 @@
+import { stageRoutineSubscriptionV1 } from "./subscriptions.js";
 // The scheduler: the half of a Routine that makes it fire.
 //
 // It owns no alarm of its own. "The Bot's Durable Object is the authority for
@@ -772,6 +773,11 @@ export class RoutineScheduler {
             enabled: false,
             updatedAt: now.toISOString(),
           } satisfies RoutineRecordV1);
+          await stageRoutineSubscriptionV1(transaction, fire.routineId, {
+            ...decoded,
+            enabled: false,
+            updatedAt: now.toISOString(),
+          });
           await appendRoutineRunEntryV1(transaction, {
             schemaVersion: 1,
             entryId: `${fire.entryId}-paused`,

package/src/shared.ts

@@ -1,3 +1,7 @@
+import {
+  decodeConnectionTriggerStatusV1,
+  type ConnectionTriggerStatusV1,
+} from "@frockbot/connection-core";
 // The Routines DTOs and commands: everything that crosses a runtime seam.
 //
 // "Cross-runtime communication uses narrow, versioned DTOs, and every inbound
@@ -92,6 +96,8 @@ export interface RoutineViewV1 {
    * its digest: the UI needs to say "a key exists", not to re-read one.
    */
   hookKeyVersion?: number;
+  eventStatus?: ConnectionTriggerStatusV1;
+  eventName?: string;
 }
 
 export interface RoutineListViewV1 {
@@ -454,7 +460,15 @@ export function decodeRoutineViewV1(value: unknown): RoutineViewV1 {
       "createdAt",
       "updatedAt",
     ],
-    ["schedule", "trigger", "lastRunAt", "nextRunAt", "hookKeyVersion"],
+    [
+      "schedule",
+      "trigger",
+      "lastRunAt",
+      "nextRunAt",
+      "hookKeyVersion",
+      "eventStatus",
+      "eventName",
+    ],
     "Routine view",
   );
   if (candidate.schemaVersion !== 1) {
@@ -514,6 +528,26 @@ export function decodeRoutineViewV1(value: unknown): RoutineViewV1 {
       ? {}
       : { hookKeyVersion: hookKeyVersion(candidate.hookKeyVersion) }),
   };
+  if (candidate.eventStatus !== undefined) {
+    if (
+      ![
+        "starting",
+        "active",
+        "paused",
+        "missing",
+        "failed",
+        "unavailable",
+      ].includes(String(candidate.eventStatus))
+    )
+      throw new RoutineDecodeError("Routine event status is invalid");
+    view.eventStatus = decodeConnectionTriggerStatusV1(candidate.eventStatus);
+  }
+  if (candidate.eventName !== undefined)
+    view.eventName = routineText(
+      candidate.eventName,
+      500,
+      "Routine event name",
+    );
   requireScheduleXorTriggerV1(view);
   return view;
 }

package/src/store.ts

@@ -1,3 +1,7 @@
+import {
+  stageRoutineSubscriptionV1,
+  routineSubscriptionMatchesV1,
+} from "./subscriptions.js";
 // The Routines authority: the Bot Durable Object's durable Routine records.
 //
 // "The Bot's Durable Object is the authority for everything Bot-scoped: …
@@ -141,7 +145,7 @@ export interface RoutineFiringSeamV1 {
     transaction: RoutineStorageWritesV1,
     input: {
       routineId: string;
-      trigger: "manual" | "webhook";
+      trigger: "manual" | "webhook" | "integration";
       discriminator: string;
       delivery?: string;
     },
@@ -375,8 +379,9 @@ export class RoutineStore {
    */
   async deliverHook(input: {
     routineId: string;
-    keyVersion: number;
-    digest: string;
+    keyVersion?: number;
+    digest?: string;
+    subscriptionId?: string;
     deliveryId: string;
     body: string;
     contentType?: string | null;
@@ -394,37 +399,62 @@ export class RoutineStore {
         throw new RoutineHookError(404, "Routine not found");
       }
       const record = decodeRoutineRecordV1(stored);
-      const held = await transaction.get<unknown>(
-        routineHookKeyRecordV1(input.routineId),
-      );
-      if (record.trigger === undefined || held === undefined) {
-        // No live key: the same answer a forged one gets, because saying
-        // "revoked" would tell a caller its guess named a real Routine.
-        throw new RoutineHookError(401, "webhook key is invalid");
-      }
-      const key = decodeRoutineHookKeyV1(held);
-      if (
-        key.keyVersion !== input.keyVersion ||
-        !constantTimeEqualsV1(key.digest, input.digest)
-      ) {
-        throw new RoutineHookError(401, "webhook key is invalid");
+      const integration = input.subscriptionId !== undefined;
+      if (integration) {
+        if (
+          record.trigger?.kind !== "connection" ||
+          input.digest !== undefined ||
+          input.keyVersion !== undefined ||
+          !(await routineSubscriptionMatchesV1(
+            transaction,
+            input.routineId,
+            input.subscriptionId!,
+          ))
+        )
+          throw new RoutineHookError(401, "Event subscription is invalid");
+      } else {
+        const held = await transaction.get<unknown>(
+          routineHookKeyRecordV1(input.routineId),
+        );
+        if (record.trigger?.kind !== "webhook" || held === undefined)
+          throw new RoutineHookError(401, "webhook key is invalid");
+        const key = decodeRoutineHookKeyV1(held);
+        if (
+          key.keyVersion !== input.keyVersion ||
+          !input.digest ||
+          !constantTimeEqualsV1(key.digest, input.digest)
+        )
+          throw new RoutineHookError(401, "webhook key is invalid");
       }
       if (!record.enabled) {
         // The key is good and the Routine is real; it is simply paused. That
         // is worth telling the caller, so a delivery can be retried later.
         throw new RoutineHookError(409, "Routine is paused");
       }
-      const receiptKey = routineDeliveryKeyV1(input.deliveryId);
+      const receiptKey = integration
+        ? `routine-event-delivery:${input.deliveryId}`
+        : routineDeliveryKeyV1(input.deliveryId);
       const seen = await transaction.get<RoutineDeliveryReceiptV1>(receiptKey);
       if (
         seen &&
-        Date.parse(seen.acceptedAt) > now.getTime() - ROUTINE_DELIVERY_TTL_MS
+        (integration ||
+          Date.parse(seen.acceptedAt) > now.getTime() - ROUTINE_DELIVERY_TTL_MS)
       ) {
         return { status: "duplicate" as const, fireId: seen.fireId };
       }
+      if (integration) {
+        const count =
+          (await transaction.get<number>("routine-event-delivery-count")) ?? 0;
+        if (count >= 100_000)
+          throw new RoutineHookError(
+            429,
+            "This Bot has reached its event history limit",
+          );
+        await transaction.put("routine-event-delivery-count", count + 1);
+      }
       const { fireId } = await firings.enqueueWithin(transaction, {
         routineId: input.routineId,
-        trigger: "webhook",
+        trigger: integration ? "integration" : "webhook",
         discriminator: `hook-${input.deliveryId.slice(0, 40)}`,
         delivery: renderRoutineDeliveryV1(input.body, input.contentType),
       });
@@ -434,7 +464,7 @@ export class RoutineStore {
         fireId,
         acceptedAt: now.toISOString(),
       } satisfies RoutineDeliveryReceiptV1);
-      await this.#trimDeliveries(transaction, now);
+      if (!integration) await this.#trimDeliveries(transaction, now);
       return { status: "accepted" as const, fireId };
     });
   }
@@ -477,7 +507,13 @@ export class RoutineStore {
   async execute(
     command: RoutineCommandV1,
     writer: RoutineWriterV1,
+    validate?: () => Promise<void>,
   ): Promise<RoutineCommandReceiptV1> {
+    if (
+      validate &&
+      !(await this.#storage.get(routineReceiptKeyV1(command.commandId)))
+    )
+      await validate();
     const fingerprint = routineCommandFingerprintV1(command);
     // A refused command is returned out of the transaction rather than thrown
     // through it: every refusal happens before the first write, so rolling back
@@ -507,6 +543,19 @@ export class RoutineStore {
       } catch (error) {
         return { ok: false, error };
       }
+      if (receipt.status !== "fired") {
+        const id =
+          receipt.status === "deleted"
+            ? receipt.routineId
+            : receipt.routine.routineId;
+        const next = await transaction.get<unknown>(routineKeyV1(id));
+        await stageRoutineSubscriptionV1(
+          transaction,
+          id,
+          next === undefined ? undefined : decodeRoutineRecordV1(next),
+          true,
+        );
+      }
       await transaction.put(receiptKey, {
         commandFingerprint: fingerprint,
         // The minted key is stripped before the receipt is stored. A key a
@@ -565,7 +614,7 @@ export class RoutineStore {
       // A webhook Routine is useless without a door key, so creating one mints
       // it in the same transaction. It is handed back once and never stored.
       const minted =
-        record.trigger === undefined
+        record.trigger?.kind !== "webhook"
           ? undefined
           : await this.#mint(transaction, record.routineId, at);
       return {
@@ -607,7 +656,7 @@ export class RoutineStore {
       command.type === "routine/rotate-key" ||
       command.type === "routine/revoke-key"
     ) {
-      if (current.trigger === undefined) {
+      if (current.trigger?.kind !== "webhook") {
         throw new RoutineDecodeError(
           `Routine "${command.routineId}" has no webhook trigger to key`,
         );
@@ -709,9 +758,9 @@ export class RoutineStore {
     const held = await transaction.get<unknown>(
       routineHookKeyRecordV1(record.routineId),
     );
-    if (record.trigger !== undefined && held === undefined) {
+    if (record.trigger?.kind === "webhook" && held === undefined) {
       minted = await this.#mint(transaction, record.routineId, at);
-    } else if (record.trigger === undefined && held !== undefined) {
+    } else if (record.trigger?.kind !== "webhook" && held !== undefined) {
       await transaction.delete(routineHookKeyRecordV1(record.routineId));
     }
     return {
@@ -722,7 +771,7 @@ export class RoutineStore {
         record,
         undefined,
         minted?.keyVersion ??
-          (record.trigger !== undefined && held !== undefined
+          (record.trigger?.kind === "webhook" && held !== undefined
             ? decodeRoutineHookKeyV1(held).keyVersion
             : undefined),
       ),

package/src/subscriptions.test.ts

@@ -0,0 +1,159 @@
+import { expect, test } from "bun:test";
+import type { RoutineSubscriptionIntentV1 } from "@frockbot/connection-core";
+import { RoutineStore } from "./store.js";
+import { createMemoryRoutineStorageV1 } from "./testing.js";
+import {
+  flushRoutineSubscriptionsV1,
+  routineSubscriptionDeadlinesV1,
+} from "./subscriptions.js";
+
+const trigger = {
+  kind: "connection" as const,
+  connectionId: "gmail-work",
+  triggerType: "GMAIL_NEW_GMAIL_MESSAGE",
+  config: {},
+};
+test("the Routine and its subscription outbox survive reconstruction; a lost acknowledgement resends the same intent", async () => {
+  const storage = createMemoryRoutineStorageV1();
+  const make = () => new RoutineStore(storage);
+  await make().execute(
+    {
+      schemaVersion: 1,
+      type: "routine/create",
+      commandId: "create",
+      botId: "bot",
+      routineId: "email",
+      name: "Email",
+      prompt: "Read the new message",
+      trigger,
+    },
+    { kind: "user" },
+  );
+  const sent: RoutineSubscriptionIntentV1[] = [];
+  await flushRoutineSubscriptionsV1(
+    storage,
+    async (intent) => {
+      sent.push(intent);
+      throw new Error("ack lost");
+    },
+    true,
+  );
+  expect(await routineSubscriptionDeadlinesV1(storage)).toHaveLength(1);
+  await flushRoutineSubscriptionsV1(
+    storage,
+    async (intent) => {
+      sent.push(intent);
+      return { schemaVersion: 1, status: "recorded" };
+    },
+    true,
+  );
+  expect(sent[0]).toEqual(sent[1]);
+  expect(await routineSubscriptionDeadlinesV1(storage)).toHaveLength(0);
+  await make().execute(
+    {
+      schemaVersion: 1,
+      type: "routine/pause",
+      commandId: "pause",
+      botId: "bot",
+      routineId: "email",
+    },
+    { kind: "user" },
+  );
+  await flushRoutineSubscriptionsV1(
+    storage,
+    async (intent) => {
+      sent.push(intent);
+      return { schemaVersion: 1, status: "recorded" };
+    },
+    true,
+  );
+  expect(sent[2]).toMatchObject({
+    subscriptionId: sent[0]!.subscriptionId,
+    enabled: false,
+    revision: 2,
+  });
+  await make().execute(
+    {
+      schemaVersion: 1,
+      type: "routine/delete",
+      commandId: "delete",
+      botId: "bot",
+      routineId: "email",
+    },
+    { kind: "user" },
+  );
+  await flushRoutineSubscriptionsV1(
+    storage,
+    async (intent) => {
+      sent.push(intent);
+      return { schemaVersion: 1, status: "recorded" };
+    },
+    true,
+  );
+  expect(sent[3]).toMatchObject({
+    subscriptionId: sent[0]!.subscriptionId,
+    enabled: false,
+    deleted: true,
+    revision: 3,
+  });
+});
+
+test("event admission uses the hook queue, keeps replay receipts beyond a day, and fences changed subscriptions", async () => {
+  const storage = createMemoryRoutineStorageV1();
+  let now = new Date("2026-09-05T00:00:00Z"),
+    firings = 0;
+  const make = () =>
+    new RoutineStore(storage, {
+      now: () => now,
+      firings: {
+        enqueueWithin: async () => ({
+          fireId: `fire-${++firings}`,
+          queued: false,
+        }),
+      },
+    });
+  await make().execute(
+    {
+      schemaVersion: 1,
+      type: "routine/create",
+      commandId: "create",
+      botId: "bot",
+      routineId: "email",
+      name: "Email",
+      prompt: "Read the new message",
+      trigger,
+    },
+    { kind: "user" },
+  );
+  const subscriptionId = await storage.get<string>(
+    "routine-subscription-current:email",
+  );
+  const event = {
+    routineId: "email",
+    subscriptionId: subscriptionId!,
+    deliveryId: "a".repeat(64),
+    body: '{"subject":"Hello"}',
+  };
+  expect((await make().deliverHook(event)).status).toBe("accepted");
+  now = new Date("2026-09-09T00:00:00Z");
+  expect((await make().deliverHook(event)).status).toBe("duplicate");
+  expect(firings).toBe(1);
+  await make().execute(
+    {
+      schemaVersion: 1,
+      type: "routine/update",
+      commandId: "change",
+      botId: "bot",
+      routineId: "email",
+      trigger: { ...trigger, config: { label: "Important" } },
+    },
+    { kind: "user" },
+  );
+  expect(await storage.get("routine-subscription-current:email")).not.toBe(
+    subscriptionId,
+  );
+  await expect(
+    make().deliverHook({ ...event, deliveryId: "b".repeat(64) }),
+  ).rejects.toMatchObject({ status: 401 });
+  expect(firings).toBe(1);
+});