@frockbot/plugin-routines 0.3.44 → 0.3.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-routines",
-  "version": "0.3.44",
+  "version": "0.3.46",
   "private": false,
   "type": "module",
   "exports": {
@@ -21,7 +21,8 @@
     "./shared": "./src/shared.ts",
     "./storage-keys": "./src/storage-keys.ts",
     "./store": "./src/store.ts",
-    "./testing": "./src/testing.ts"
+    "./testing": "./src/testing.ts",
+    "./subscriptions": "./src/subscriptions.ts"
   },
   "frockbot": {
     "manifest": "./frockbot.json"
@@ -32,15 +33,16 @@
     "typecheck": "vue-tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/client-core": "0.3.44",
-    "@frockbot/client-ui": "0.3.44",
-    "@frockbot/configuration-core": "0.3.44",
-    "@frockbot/kernel-agent-loop": "0.3.44",
-    "@frockbot/kernel-contracts": "0.3.44",
-    "@frockbot/plugin-shell": "0.3.44",
+    "@frockbot/client-core": "0.3.46",
+    "@frockbot/client-ui": "0.3.46",
+    "@frockbot/configuration-core": "0.3.46",
+    "@frockbot/kernel-agent-loop": "0.3.46",
+    "@frockbot/kernel-contracts": "0.3.46",
+    "@frockbot/plugin-shell": "0.3.46",
     "cordis": "4.0.0-rc.8",
     "croner": "10.0.1",
-    "vue": "3.5.41"
+    "vue": "3.5.41",
+    "@frockbot/connection-core": "0.3.46"
   },
   "devDependencies": {
     "@types/bun": "1.4.0",

package/src/agent.ts

@@ -1,3 +1,8 @@
+import {
+  decodeConnectionTriggerV1,
+  type ConnectionTriggerV1,
+  type ConnectionTriggerCatalogV1,
+} from "@frockbot/connection-core";
 // The Routines runtime Contribution: one tool, `routine_manage`.
 //
 // GrokBot's `update_state target=routine {create,update,pause,resume,delete}`
@@ -50,6 +55,7 @@ export interface RoutinesRuntimeHostV1 {
   botId: string;
   writer?: RoutineWriterIdentityV1;
   list(): Promise<RoutineListViewV1>;
+  listTriggers?(): Promise<ConnectionTriggerCatalogV1>;
   execute(
     command: RoutineCommandV1,
     writer: RoutineWriterV1,
@@ -63,6 +69,7 @@ export const ROUTINE_MANAGE_ACTIONS = [
   "resume",
   "delete",
   "run_now",
+  "list_triggers",
 ] as const;
 
 export type RoutineManageActionV1 = (typeof ROUTINE_MANAGE_ACTIONS)[number];
@@ -92,10 +99,28 @@ const ROUTINE_MANAGE_INPUT_SCHEMA = {
         "A five-field cron expression, or @hourly, @daily, @weekly, @monthly, or @every 15m. Optionally prefixed with CRON_TZ=<zone>. A Routine has a schedule or a webhook trigger, never both.",
     },
     trigger: {
-      type: "string",
-      enum: ["webhook"],
+      oneOf: [
+        { type: "string", enum: ["webhook"] },
+        {
+          type: "object",
+          properties: {
+            composio: {
+              type: "object",
+              properties: {
+                connectionId: { type: "string" },
+                triggerType: { type: "string" },
+                config: { type: "object" },
+              },
+              required: ["connectionId", "triggerType", "config"],
+              additionalProperties: false,
+            },
+          },
+          required: ["composio"],
+          additionalProperties: false,
+        },
+      ],
       description:
-        "Fire on a delivered webhook instead of on a clock. A Routine has a schedule or a trigger, never both.",
+        "Fire on an event from an existing connected account. Use list_triggers first to find the account, event type and configuration schema. A Routine has a schedule or a trigger, never both.",
     },
     timezone: {
       type: "string",
@@ -125,7 +150,7 @@ interface RoutineManageInputV1 {
   name?: string;
   prompt?: string;
   schedule?: string;
-  trigger?: "webhook";
+  trigger?: "webhook" | { composio: ConnectionTriggerV1 };
   timezone?: string;
   userAsked?: boolean;
 }
@@ -164,8 +189,18 @@ function decodeRoutineManageInputV1(input: unknown): RoutineManageInputV1 {
     }
     return candidate;
   };
-  if (value.trigger !== undefined && value.trigger !== "webhook") {
-    throw new RoutineDecodeError('routine_manage trigger must be "webhook"');
+  let trigger: RoutineManageInputV1["trigger"];
+  if (value.trigger === "webhook") trigger = "webhook";
+  else if (value.trigger !== undefined) {
+    if (
+      !value.trigger ||
+      typeof value.trigger !== "object" ||
+      Array.isArray(value.trigger) ||
+      Object.keys(value.trigger).some((key) => key !== "composio") ||
+      !("composio" in value.trigger)
+    )
+      throw new RoutineDecodeError("Choose a service event or webhook trigger");
+    trigger = { composio: decodeConnectionTriggerV1(value.trigger.composio) };
   }
   if (value.userAsked !== undefined && typeof value.userAsked !== "boolean") {
     throw new RoutineDecodeError("routine_manage userAsked must be a boolean");
@@ -182,7 +217,7 @@ function decodeRoutineManageInputV1(input: unknown): RoutineManageInputV1 {
     ...(optional("schedule") === undefined
       ? {}
       : { schedule: optional("schedule")! }),
-    ...(value.trigger === undefined ? {} : { trigger: "webhook" as const }),
+    ...(trigger === undefined ? {} : { trigger }),
     ...(optional("timezone") === undefined
       ? {}
       : { timezone: optional("timezone")! }),
@@ -228,7 +263,12 @@ export function routineManageCommandV1(
       ...(input.schedule === undefined ? {} : { schedule: input.schedule }),
       ...(input.trigger === undefined
         ? {}
-        : { trigger: { kind: input.trigger } }),
+        : {
+            trigger:
+              input.trigger === "webhook"
+                ? { kind: "webhook" }
+                : { kind: "connection", ...input.trigger.composio },
+          }),
       ...(input.timezone === undefined ? {} : { timezone: input.timezone }),
     });
   }
@@ -247,7 +287,12 @@ export function routineManageCommandV1(
       ...(input.schedule === undefined ? {} : { schedule: input.schedule }),
       ...(input.trigger === undefined
         ? {}
-        : { trigger: { kind: input.trigger } }),
+        : {
+            trigger:
+              input.trigger === "webhook"
+                ? { kind: "webhook" }
+                : { kind: "connection", ...input.trigger.composio },
+          }),
       ...(input.timezone === undefined ? {} : { timezone: input.timezone }),
     });
   }
@@ -295,7 +340,7 @@ export function createRoutineManageTool(
     // video roles. See `@frockbot/plugin-subagents` `SUBAGENT_TOOL_REACH_V1`.
     admission: { subagentRoles: ["executor"] },
     description: [
-      "Create, edit, pause, resume, delete, or immediately run one of your own Routines.",
+      "Create, edit, pause, resume, delete, or immediately run one of your own Routines. Use list_triggers to list events and configuration schemas on the User’s existing connected accounts.",
       "A Routine is a standing instruction that fires on a schedule or on a delivered webhook,",
       `as its own Turn rather than inside this conversation. Names are at most ${ROUTINE_NAME_MAX_LENGTH}`,
       `characters and prompts at most ${ROUTINE_PROMPT_MAX_LENGTH}.`,
@@ -322,6 +367,13 @@ export function createRoutineManageTool(
       let command: RoutineCommandV1;
       try {
         decoded = decodeRoutineManageInputV1(input);
+        if (decoded.action === "list_triggers")
+          return {
+            content: JSON.stringify(
+              (await host.listTriggers?.()) ?? { schemaVersion: 1, items: [] },
+            ),
+            isError: false,
+          };
         command = routineManageCommandV1(decoded, {
           botId: host.botId,
           commandId: routineToolCommandIdV1(context.effectId),
@@ -374,7 +426,9 @@ export function createRoutineManageTool(
       const routine = receipt.routine;
       const timing = routine.schedule
         ? `schedule ${routine.schedule} (${routine.timezone})`
-        : "webhook trigger";
+        : routine.trigger?.kind === "connection"
+          ? (routine.eventName ?? "a service event")
+          : "webhook trigger";
       return {
         content: [
           `Routine "${routine.name}" (${routine.routineId}) is ${

package/src/backend.ts

@@ -1,3 +1,7 @@
+import {
+  decodeConnectionTriggerCatalogV1,
+  type ConnectionTriggerCatalogV1,
+} from "@frockbot/connection-core";
 // The Routines gateway Contribution: the authenticated HTTP surface.
 //
 // Three routes, all Bot-scoped and all beside `/api/bots/:id/settings`:
@@ -73,6 +77,10 @@ export interface RoutinesGatewayHost {
     },
   ): Promise<RoutineHookDeliveryReceiptV1>;
   listRoutines(userId: string, botId: string): Promise<RoutineListViewV1>;
+  listTriggers?(
+    userId: string,
+    botId: string,
+  ): Promise<ConnectionTriggerCatalogV1>;
   executeRoutineCommand(
     userId: string,
     botId: string,
@@ -117,6 +125,7 @@ export interface RoutinesBackendRouteContribution {
 }
 
 const ROUTINES = /^\/api\/bots\/([^/]+)\/routines$/;
+const ROUTINE_TRIGGERS = /^\/api\/bots\/([^/]+)\/routines\/triggers$/;
 const ROUTINE_INBOX = /^\/api\/bots\/([^/]+)\/routines\/inbox$/;
 const ROUTINE_RUNS = /^\/api\/bots\/([^/]+)\/routines\/([^/]+)\/runs$/;
 const ROUTINE_HOOK = /^\/api\/bots\/([^/]+)\/routines\/([^/]+)\/hook$/;
@@ -270,16 +279,31 @@ export function createRoutinesBackendContribution(
     packageId: "routines",
     async route(request, url, context) {
       if (!context.userId) return undefined;
+      const triggers = ROUTINE_TRIGGERS.exec(url.pathname);
       const list = ROUTINES.exec(url.pathname);
       const inbox = ROUTINE_INBOX.exec(url.pathname);
       const runs = ROUTINE_RUNS.exec(url.pathname);
       const run = ROUTINE_RUN.exec(url.pathname);
-      if (!list && !inbox && !runs && !run) return undefined;
+      if (!triggers && !list && !inbox && !runs && !run) return undefined;
       if ([...url.searchParams.keys()].length > 0) {
         return jsonError(400, "Routine routes take no query parameters");
       }
       try {
-        const botId = pathSegment((list ?? inbox ?? runs ?? run)![1]!);
+        const botId = pathSegment(
+          (triggers ?? list ?? inbox ?? runs ?? run)![1]!,
+        );
+        if (triggers) {
+          if (request.method !== "GET")
+            return jsonError(405, "method not allowed");
+          return Response.json(
+            decodeConnectionTriggerCatalogV1(
+              (await host.listTriggers?.(context.userId, botId)) ?? {
+                schemaVersion: 1,
+                items: [],
+              },
+            ),
+          );
+        }
         if (run) {
           if (request.method !== "GET") {
             return jsonError(405, "method not allowed");

package/src/client/RoutinesSection.vue

@@ -18,7 +18,8 @@ import {
 } from "@frockbot/client-core";
 import { frockBotWebDataKey } from "@frockbot/plugin-shell/shared";
 import { settingsLinkV1 } from "@frockbot/plugin-shell/settings-links";
-import { computed, inject, reactive, ref, watch } from "vue";
+import { computed, inject, reactive, ref, toRaw, watch } from "vue";
+import { triggerObject } from "@frockbot/connection-core";
 import type { RoutineViewV1 } from "../shared.js";
 import { routinesStateKey } from "./state.js";
 
@@ -56,11 +57,85 @@ const form = reactive({
   routineId: undefined as string | undefined,
   name: "",
   prompt: "",
-  timing: "schedule" as "schedule" | "webhook",
+  timing: "schedule" as "schedule" | "webhook" | "connection",
   schedule: "",
+  connectionId: "",
+  triggerType: "",
+  config: {} as Record<string, unknown>,
   timezone: "UTC",
 });
 
+const accounts = computed(() => [
+  ...new Map(
+    (routines.value.triggers ?? []).map((item) => [item.connectionId, item]),
+  ).values(),
+]);
+const events = computed(() =>
+  (routines.value.triggers ?? []).filter(
+    (item) => item.connectionId === form.connectionId,
+  ),
+);
+const selectedEvent = computed(() =>
+  events.value.find((item) => item.triggerType === form.triggerType),
+);
+const eventFields = computed(() => {
+  const schema = selectedEvent.value?.configSchema;
+  if (!schema || !triggerObject(schema.properties)) return [];
+  return Object.entries(schema.properties).flatMap(([key, value]) =>
+    triggerObject(value)
+      ? [
+          {
+            key,
+            label:
+              typeof value.title === "string"
+                ? value.title
+                : key
+                    .replaceAll("_", " ")
+                    .replace(/^./, (letter) => letter.toUpperCase()),
+            hint:
+              typeof value.description === "string"
+                ? value.description
+                : undefined,
+            type: value.type,
+            options: Array.isArray(value.enum)
+              ? value.enum.filter(
+                  (item): item is string => typeof item === "string",
+                )
+              : [],
+            required:
+              Array.isArray(schema.required) && schema.required.includes(key),
+          },
+        ]
+      : [],
+  );
+});
+function selectEvent(): void {
+  form.config = {};
+  const properties = selectedEvent.value?.configSchema.properties;
+  if (triggerObject(properties))
+    for (const [key, value] of Object.entries(properties)) {
+      if (triggerObject(value) && value.default !== undefined)
+        form.config[key] = structuredClone(toRaw(value.default));
+    }
+}
+function selectAccount(): void {
+  form.triggerType = events.value[0]?.triggerType ?? "";
+  selectEvent();
+}
+function eventState(routine: RoutineViewV1): string {
+  return (
+    {
+      active: "Listening",
+      starting: "Starting…",
+      paused: "Paused",
+      missing: "Listening stopped — edit and save to restart",
+      failed: "Could not start listening — review the event settings",
+      unavailable: "Connection unavailable — check Connectors",
+    }[routine.eventStatus ?? "unavailable"] ??
+    "Connection unavailable — check Connectors"
+  );
+}
+
 /**
  * The reason the last save was refused, held beside the form rather than in
  * the section header. The header sits above every Routine card, so on a Bot
@@ -125,7 +200,9 @@ async function copyHook(): Promise<void> {
 function summary(routine: RoutineViewV1): string {
   return routine.schedule
     ? `${routine.schedule} · ${routine.timezone}`
-    : "Webhook trigger";
+    : routine.trigger?.kind === "connection"
+      ? (routine.eventName ?? "Connected account event")
+      : "Webhook trigger";
 }
 
 /** A durable moment, read in the Routine's own zone — the one it fires on. */
@@ -134,10 +211,13 @@ function moment(routine: RoutineViewV1, iso: string): string {
 }
 
 function startCreate(): void {
+  if (botId.value) void routines.value.load(botId.value);
   form.routineId = undefined;
   form.name = "";
   form.prompt = "";
   form.timing = "schedule";
+  form.connectionId = accounts.value[0]?.connectionId ?? "";
+  selectAccount();
   form.schedule = "0 9 * * *";
   // The reader's own zone, not UTC: a schedule is almost always meant in the
   // day the person writing it is living in, and the Bot picks the same when it
@@ -151,7 +231,16 @@ function startEdit(routine: RoutineViewV1): void {
   form.routineId = routine.routineId;
   form.name = routine.name;
   form.prompt = routine.prompt;
-  form.timing = routine.schedule ? "schedule" : "webhook";
+  form.timing = routine.schedule
+    ? "schedule"
+    : routine.trigger?.kind === "connection"
+      ? "connection"
+      : "webhook";
+  if (routine.trigger?.kind === "connection") {
+    form.connectionId = routine.trigger.connectionId;
+    form.triggerType = routine.trigger.triggerType;
+    form.config = structuredClone(toRaw(routine.trigger.config));
+  }
   form.schedule = routine.schedule ?? "";
   form.timezone = routine.timezone;
   saveError.value = undefined;
@@ -163,13 +252,46 @@ async function submit(): Promise<void> {
   if (!id) return;
   saveError.value = undefined;
   try {
+    if (form.timing === "connection" && !selectedEvent.value)
+      throw new Error("Choose an available account and event");
+    const config = Object.fromEntries(
+      Object.entries(form.config).filter(
+        ([, value]) => value !== "" && value !== undefined,
+      ),
+    );
+    for (const field of eventFields.value) {
+      if (field.required && config[field.key] === undefined)
+        throw new Error(`Enter ${field.label.toLowerCase()}`);
+      if (
+        config[field.key] !== undefined &&
+        (field.type === "array" || field.type === "object") &&
+        typeof config[field.key] === "string"
+      ) {
+        try {
+          config[field.key] = JSON.parse(String(config[field.key]));
+        } catch {
+          throw new Error(
+            `Check ${field.label.toLowerCase()}: enter valid JSON`,
+          );
+        }
+      }
+    }
     await routines.value.save(id, {
       ...(form.routineId ? { routineId: form.routineId } : {}),
       name: form.name.trim(),
       prompt: form.prompt.trim(),
       ...(form.timing === "schedule"
         ? { schedule: form.schedule.trim() }
-        : { trigger: { kind: "webhook" as const } }),
+        : form.timing === "connection"
+          ? {
+              trigger: {
+                kind: "connection" as const,
+                connectionId: form.connectionId,
+                triggerType: form.triggerType,
+                config,
+              },
+            }
+          : { trigger: { kind: "webhook" as const } }),
       timezone: form.timezone.trim(),
     });
     formOpen.value = false;
@@ -185,7 +307,9 @@ async function submit(): Promise<void> {
     saveError.value =
       serverRefusalMessageV1(error) ??
       routines.value.error ??
-      presentClientFailureV1(error, "save the Routine");
+      (error instanceof Error
+        ? error.message
+        : presentClientFailureV1(error, "save the Routine"));
   }
 }
 
@@ -232,8 +356,8 @@ async function toggleLog(routineId: string): Promise<void> {
       <span class="routines__intro">
         <strong>Routines</strong>
         <small>
-          Standing instructions this Bot runs on a schedule, or when a webhook
-          fires.
+          Standing instructions this Bot runs on a schedule or when something
+          happens.
         </small>
       </span>
       <UiButton type="button" :disabled="!botId" @click="startCreate">
@@ -291,6 +415,13 @@ async function toggleLog(routineId: string): Promise<void> {
           </UiButton>
         </div>
       </div>
+      <p
+        v-if="routine.trigger?.kind === 'connection'"
+        class="routines__note"
+        role="status"
+      >
+        {{ eventState(routine) }}
+      </p>
       <dl class="routine-card__facts">
         <div>
           <dt>Next run</dt>
@@ -301,7 +432,7 @@ async function toggleLog(routineId: string): Promise<void> {
             <template v-else>—</template>
           </dd>
         </div>
-        <div v-if="routine.trigger">
+        <div v-if="routine.trigger?.kind === 'webhook'">
           <dt>Webhook key</dt>
           <dd>
             {{
@@ -354,7 +485,7 @@ async function toggleLog(routineId: string): Promise<void> {
           Run now
         </UiButton>
         <UiButton
-          v-if="routine.trigger"
+          v-if="routine.trigger?.kind === 'webhook'"
           type="button"
           :disabled="routines.busy"
           @click="botId && routines.rotateKey(botId, routine.routineId)"
@@ -362,7 +493,7 @@ async function toggleLog(routineId: string): Promise<void> {
           {{ routine.hookKeyVersion ? "Rotate key" : "Mint key" }}
         </UiButton>
         <UiButton
-          v-if="routine.trigger && routine.hookKeyVersion"
+          v-if="routine.trigger?.kind === 'webhook' && routine.hookKeyVersion"
           type="button"
           :disabled="routines.busy"
           @click="botId && routines.revokeKey(botId, routine.routineId)"
@@ -469,7 +600,103 @@ async function toggleLog(routineId: string): Promise<void> {
           <input v-model="form.timing" type="radio" value="webhook" />
           <span>A webhook</span>
         </label>
+        <label>
+          <input v-model="form.timing" type="radio" value="connection" />
+          <span>An event in a connected account</span>
+        </label>
       </fieldset>
+      <template v-if="form.timing === 'connection'">
+        <p
+          v-if="routines.triggerError"
+          class="routine-form__error"
+          role="alert"
+        >
+          {{ routines.triggerError }}
+        </p>
+        <p v-else-if="!accounts.length" class="routines__note">
+          No events are available for your connected accounts yet.
+        </p>
+        <template v-else>
+          <UiField label="Account">
+            <select v-model="form.connectionId" @change="selectAccount">
+              <option disabled value="">Choose an account</option>
+              <option
+                v-for="account in accounts"
+                :key="account.connectionId"
+                :value="account.connectionId"
+              >
+                {{ account.connectorName }} · {{ account.accountName }}
+              </option>
+            </select>
+          </UiField>
+          <UiField label="When" :hint="selectedEvent?.description">
+            <select v-model="form.triggerType" @change="selectEvent">
+              <option disabled value="">Choose an event</option>
+              <option
+                v-for="event in events"
+                :key="event.triggerType"
+                :value="event.triggerType"
+              >
+                {{ event.name }}
+              </option>
+            </select>
+          </UiField>
+          <UiField
+            v-for="field in eventFields"
+            :key="field.key"
+            :label="field.label"
+            :hint="field.hint"
+          >
+            <select
+              v-if="field.options.length"
+              v-model="form.config[field.key]"
+              :required="field.required"
+            >
+              <option v-if="!field.required" value="">Any</option>
+              <option
+                v-for="option in field.options"
+                :key="option"
+                :value="option"
+              >
+                {{ option }}
+              </option>
+            </select>
+            <input
+              v-else-if="field.type === 'boolean'"
+              v-model="form.config[field.key]"
+              type="checkbox"
+            />
+            <input
+              v-else-if="field.type === 'number' || field.type === 'integer'"
+              v-model.number="form.config[field.key]"
+              type="number"
+              :step="field.type === 'integer' ? 1 : 'any'"
+              :required="field.required"
+            />
+            <textarea
+              v-else-if="field.type === 'array' || field.type === 'object'"
+              :value="
+                typeof form.config[field.key] === 'string'
+                  ? String(form.config[field.key])
+                  : JSON.stringify(form.config[field.key], null, 2)
+              "
+              @input="
+                form.config[field.key] = (
+                  $event.target as HTMLTextAreaElement
+                ).value
+              "
+              :required="field.required"
+              rows="3"
+            />
+            <input
+              v-else
+              v-model="form.config[field.key]"
+              :required="field.required"
+              maxlength="8000"
+            />
+          </UiField>
+        </template>
+      </template>
       <UiField
         v-if="form.timing === 'schedule'"
         label="Schedule"
@@ -493,7 +720,7 @@ async function toggleLog(routineId: string): Promise<void> {
       >
         {{ scheduleError }}
       </p>
-      <p v-else class="routines__note">
+      <p v-if="form.timing === 'webhook'" class="routines__note">
         A delivery key is minted when the Routine is saved, and shown once.
       </p>
       <UiField label="Time zone">
@@ -754,7 +981,8 @@ async function toggleLog(routineId: string): Promise<void> {
 
 .routine-form__timing {
   display: flex;
-  gap: 12px;
+  flex-direction: column;
+  gap: 8px;
   border: 0;
   margin: 0;
   padding: 0;

package/src/client/RoutinesSummary.vue

@@ -63,7 +63,9 @@ watch(
       <li v-for="routine in rows" :key="routine.routineId">
         <span>
           <strong>{{ routine.name }}</strong>
-          <small>{{ routine.schedule ?? "Webhook" }}</small>
+          <small>{{
+            routine.schedule ?? routine.eventName ?? "Webhook"
+          }}</small>
         </span>
         <small>{{ routine.enabled ? "On" : "Paused" }}</small>
       </li>

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);
+});

package/src/subscriptions.ts

@@ -0,0 +1,185 @@
+import { canonicalCommandFingerprintV1 } from "@frockbot/configuration-core";
+import {
+  decodeRoutineSubscriptionIntentV1,
+  type RoutineSubscriptionIntentV1,
+} from "@frockbot/connection-core";
+import type { RoutineRecordV1 } from "./records.js";
+import type {
+  RoutineStorageReadsV1,
+  RoutineStorageWritesV1,
+  RoutineStorageV1,
+} from "./store.js";
+
+const PREFIX = "routine-subscription:",
+  POINTER = "routine-subscription-current:";
+interface Binding {
+  schemaVersion: 1;
+  intent: RoutineSubscriptionIntentV1;
+  pending: boolean;
+  dueAt: number;
+}
+function decode(value: unknown): Binding {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    !("schemaVersion" in value) ||
+    value.schemaVersion !== 1 ||
+    !("intent" in value) ||
+    !("pending" in value) ||
+    typeof value.pending !== "boolean" ||
+    !("dueAt" in value) ||
+    typeof value.dueAt !== "number" ||
+    !Number.isFinite(value.dueAt)
+  )
+    throw new Error("Routine event binding is invalid");
+  return {
+    schemaVersion: 1,
+    intent: decodeRoutineSubscriptionIntentV1(value.intent),
+    pending: value.pending,
+    dueAt: value.dueAt,
+  };
+}
+/** Staged in the same Bot transaction as the Routine; no provider call occurs here. */
+export async function stageRoutineSubscriptionV1(
+  tx: RoutineStorageWritesV1,
+  routineId: string,
+  next?: RoutineRecordV1,
+  force = false,
+) {
+  const current = await tx.get<string>(`${POINTER}${routineId}`);
+  const held = current
+    ? decode(await tx.get(`${PREFIX}${current}`))
+    : undefined;
+  const trigger =
+    next?.trigger?.kind === "connection"
+      ? {
+          connectionId: next.trigger.connectionId,
+          triggerType: next.trigger.triggerType,
+          config: next.trigger.config,
+        }
+      : undefined;
+  const same =
+    held &&
+    trigger &&
+    canonicalCommandFingerprintV1("trigger", held.intent.trigger) ===
+      canonicalCommandFingerprintV1("trigger", trigger);
+  if (same && held) {
+    if (held.intent.enabled === next!.enabled && !force) return;
+    await tx.put(`${PREFIX}${current}`, {
+      schemaVersion: 1,
+      intent: {
+        ...held.intent,
+        revision: held.intent.revision + 1,
+        enabled: next!.enabled,
+      },
+      pending: true,
+      dueAt: Date.now(),
+    } satisfies Binding);
+    return;
+  }
+  if (held && !held.intent.deleted) {
+    await tx.put(`${PREFIX}${current}`, {
+      schemaVersion: 1,
+      intent: {
+        ...held.intent,
+        revision: held.intent.revision + 1,
+        enabled: false,
+        deleted: true,
+      },
+      pending: true,
+      dueAt: Date.now(),
+    } satisfies Binding);
+    await tx.delete(`${POINTER}${routineId}`);
+  }
+  if (!trigger) return;
+  if ((await tx.list({ prefix: PREFIX, limit: 1000 })).size >= 1000)
+    throw new Error(
+      "This Bot has reached its event subscription history limit",
+    );
+  const subscriptionId = crypto.randomUUID();
+  await tx.put(`${PREFIX}${subscriptionId}`, {
+    schemaVersion: 1,
+    intent: {
+      schemaVersion: 1,
+      subscriptionId,
+      routineId,
+      revision: 1,
+      enabled: next!.enabled,
+      deleted: false,
+      trigger,
+    },
+    pending: true,
+    dueAt: Date.now(),
+  } satisfies Binding);
+  await tx.put(`${POINTER}${routineId}`, subscriptionId);
+}
+export async function routineSubscriptionMatchesV1(
+  tx: RoutineStorageReadsV1,
+  routineId: string,
+  subscriptionId: string,
+): Promise<boolean> {
+  if ((await tx.get(`${POINTER}${routineId}`)) !== subscriptionId) return false;
+  const binding = decode(await tx.get(`${PREFIX}${subscriptionId}`));
+  return binding.intent.enabled && !binding.intent.deleted;
+}
+export async function routineSubscriptionDeadlinesV1(
+  tx: RoutineStorageReadsV1,
+): Promise<number[]> {
+  return [...(await tx.list({ prefix: PREFIX })).values()]
+    .map(decode)
+    .filter((binding) => binding.pending)
+    .map((binding) => binding.dueAt);
+}
+export async function flushRoutineSubscriptionsV1(
+  storage: RoutineStorageV1,
+  send: (intent: RoutineSubscriptionIntentV1) => Promise<unknown>,
+  force = false,
+): Promise<void> {
+  for (const [key, value] of await storage.list({ prefix: PREFIX })) {
+    const binding = decode(value);
+    if (!binding.pending || (!force && binding.dueAt > Date.now())) continue;
+    await storage.transaction(async (tx) => {
+      const live = decode(await tx.get(key));
+      if (live.intent.revision === binding.intent.revision)
+        await tx.put(key, { ...live, dueAt: Date.now() + 60_000 });
+    });
+    try {
+      const receipt = await send(binding.intent);
+      if (
+        !receipt ||
+        typeof receipt !== "object" ||
+        !("schemaVersion" in receipt) ||
+        receipt.schemaVersion !== 1 ||
+        !("status" in receipt) ||
+        receipt.status !== "recorded"
+      )
+        throw new Error("Routine subscription was not acknowledged");
+      await storage.transaction(async (tx) => {
+        const live = decode(await tx.get(key));
+        if (live.intent.revision === binding.intent.revision)
+          await tx.put(key, { ...live, pending: false });
+      });
+    } catch {
+      /* The persisted deadline retries the same desired revision. */
+    }
+  }
+}
+
+export async function routineSubscriptionBindingsV1(
+  storage: RoutineStorageReadsV1,
+): Promise<Record<string, string>> {
+  const result: Record<string, string> = {};
+  for (const [key, id] of await storage.list<unknown>({ prefix: POINTER })) {
+    if (typeof id !== "string")
+      throw new Error("Routine event binding is invalid");
+    const held = decode(await storage.get(`${PREFIX}${id}`));
+    if (
+      held.intent.subscriptionId !== id ||
+      held.intent.routineId !== key.slice(POINTER.length) ||
+      held.intent.deleted
+    )
+      throw new Error("Routine event binding is invalid");
+    result[held.intent.routineId] = id;
+  }
+  return result;
+}