@frockbot/plugin-routines 0.0.0 → 0.1.1

package/src/client/RoutinesSummary.vue

@@ -0,0 +1,150 @@
+<script setup lang="ts">
+// The Routines glance in the default Bot panel. Every row comes from the same
+// durable listing the full editor reads.
+import { UiAnchor, UiIcon } from "@frockbot/client-ui";
+import { frockBotWebDataKey } from "@frockbot/plugin-shell/shared";
+import { settingsLinkV1 } from "@frockbot/plugin-shell/settings-links";
+import { computed, inject, watch } from "vue";
+import { routinesStateKey } from "./state.js";
+
+const providedWeb = inject(frockBotWebDataKey);
+const providedState = inject(routinesStateKey);
+if (!providedWeb || !providedState) {
+  throw new Error("Routines client services were not provided");
+}
+const web = providedWeb;
+const routines = providedState;
+const botId = computed(() => web.value.activeBotId);
+const rows = computed(() =>
+  routines.value.botId === botId.value ? routines.value.routines : [],
+);
+const link = computed(() =>
+  settingsLinkV1({ anchor: "bot-info-routines", botId: botId.value }),
+);
+const sectionLink = computed(() =>
+  settingsLinkV1({ anchor: "bot-routines", botId: botId.value }),
+);
+
+watch(
+  botId,
+  (id) => {
+    if (!id) return;
+    if (routines.value.botId !== id || !routines.value.loaded) {
+      void routines.value.load(id);
+    }
+  },
+  { immediate: true },
+);
+</script>
+
+<template>
+  <UiAnchor
+    as="section"
+    anchor="bot-info-routines"
+    label="Routines"
+    :href="link"
+    class="routines-summary"
+  >
+    <header class="routines-summary__head">
+      <h3>Routines</h3>
+      <a
+        class="routines-summary__add"
+        :href="sectionLink"
+        aria-label="Open Routines editor"
+        title="Open Routines editor"
+      >
+        <UiIcon name="plus" size="sm" />
+      </a>
+    </header>
+    <p v-if="rows.length === 0" class="routines-summary__empty">
+      No Routines yet.
+    </p>
+    <ul v-else class="routines-summary__rows">
+      <li v-for="routine in rows" :key="routine.routineId">
+        <span>
+          <strong>{{ routine.name }}</strong>
+          <small>{{ routine.schedule ?? "Webhook" }}</small>
+        </span>
+        <small>{{ routine.enabled ? "On" : "Paused" }}</small>
+      </li>
+    </ul>
+  </UiAnchor>
+</template>
+
+<style scoped>
+.routines-summary {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding-right: var(--frock-control-sm);
+}
+
+.routines-summary__head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.routines-summary__add {
+  display: grid;
+  width: var(--frock-control-sm);
+  height: var(--frock-control-sm);
+  place-items: center;
+  border-radius: var(--frock-radius-control);
+  color: var(--frock-text);
+}
+
+.routines-summary__add:hover {
+  background: var(--frock-fill-hover);
+}
+
+.routines-summary__head h3 {
+  flex: 1 1 auto;
+  margin: 0;
+  font-size: var(--frock-text-md);
+  font-weight: 600;
+}
+
+.routines-summary__empty {
+  margin: 0;
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-sm);
+}
+
+.routines-summary__rows {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.routines-summary__rows li {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  padding: 9px 0;
+  border-bottom: 1px solid var(--frock-border);
+}
+
+.routines-summary__rows li > span {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+}
+
+.routines-summary__rows strong {
+  overflow: hidden;
+  color: var(--frock-text);
+  font-size: var(--frock-text-sm);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.routines-summary__rows small {
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-sm);
+}
+</style>

package/src/client/index.test.ts

@@ -0,0 +1,209 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  ClientPluginContext,
+  ClientSlotRegistration,
+} from "@frockbot/client-core";
+import { routinesClientPlugin } from "./index.js";
+import { routinesStateKey, type RoutinesClientState } from "./state.js";
+
+const ROUTINE = {
+  schemaVersion: 1,
+  routineId: "brief",
+  name: "Morning brief",
+  prompt: "Summarize overnight email.",
+  schedule: "0 7 * * *",
+  timezone: "Australia/Sydney",
+  enabled: true,
+  createdBy: { kind: "user" },
+  updatedBy: { kind: "user" },
+  createdAt: "2026-08-31T00:00:00.000Z",
+  updatedAt: "2026-08-31T00:00:00.000Z",
+};
+
+function mount(
+  overrides: {
+    hostedRequest?: ClientPluginContext["transport"]["hostedRequest"];
+  } = {},
+): {
+  state: { value: RoutinesClientState };
+  slots: ClientSlotRegistration[];
+  calls: Array<[string, string | undefined, string | undefined]>;
+  dispose(): void;
+} {
+  const slots: ClientSlotRegistration[] = [];
+  const calls: Array<[string, string | undefined, string | undefined]> = [];
+  let state: unknown;
+  const context: ClientPluginContext = {
+    transport: {
+      turn: () => Promise.resolve({ runId: "run", text: "", events: [] }),
+      hostedRequest:
+        overrides.hostedRequest ??
+        ((path, method, body) => {
+          calls.push([path, method, body]);
+          if (method === "POST") {
+            return Promise.resolve({
+              schemaVersion: 1,
+              commandId: (JSON.parse(body ?? "{}") as { commandId: string })
+                .commandId,
+              status: "applied",
+              routine: ROUTINE,
+            });
+          }
+          if (path.endsWith("/runs")) {
+            return Promise.resolve({
+              schemaVersion: 1,
+              botId: "scout",
+              routineId: "brief",
+              entries: [],
+            });
+          }
+          return Promise.resolve({
+            schemaVersion: 1,
+            botId: "scout",
+            routines: [ROUTINE],
+          });
+        }),
+    },
+    inject: () => {
+      throw new Error("unexpected client provider");
+    },
+    provide: (key, value) => {
+      if (key === routinesStateKey) state = value;
+      return () => {};
+    },
+    slot: (registration) => {
+      slots.push(registration);
+      return () => slots.splice(slots.indexOf(registration), 1);
+    },
+  };
+  const disposers = routinesClientPlugin(context);
+  if (!Array.isArray(disposers)) throw new Error("expected registrations");
+  return {
+    state: state as { value: RoutinesClientState },
+    slots,
+    calls,
+    dispose: () => {
+      for (const dispose of disposers.toReversed()) dispose();
+    },
+  };
+}
+
+describe("Routines client contribution", () => {
+  test("mounts into the settings outlet, the header and the Bot panel", () => {
+    const mounted = mount();
+    expect(mounted.slots.map((slot) => slot.slot)).toEqual([
+      "frockbot.bot-settings-sections",
+      "frockbot.header-actions",
+      "frockbot.bot-panel-sections",
+    ]);
+    mounted.dispose();
+  });
+
+  test("loads a Bot's Routines and decodes them at the seam", async () => {
+    const mounted = mount();
+    await mounted.state.value.load("scout");
+    expect(mounted.state.value.routines).toHaveLength(1);
+    expect(mounted.state.value.botId).toBe("scout");
+    expect(mounted.calls[0]).toEqual([
+      "/api/bots/scout/routines",
+      undefined,
+      undefined,
+    ]);
+    mounted.dispose();
+  });
+
+  test("submits one versioned command per action, each with its own key", async () => {
+    const mounted = mount();
+    await mounted.state.value.save("scout", {
+      name: "Morning brief",
+      prompt: "Summarize overnight email.",
+      schedule: "0 7 * * *",
+      timezone: "Australia/Sydney",
+    });
+    await mounted.state.value.setEnabled("scout", "brief", false);
+    await mounted.state.value.remove("scout", "brief");
+    const posts = mounted.calls
+      .filter(([, method]) => method === "POST")
+      .map(
+        ([, , body]) =>
+          JSON.parse(body ?? "{}") as { type: string; commandId: string },
+      );
+    expect(posts.map((post) => post.type)).toEqual([
+      "routine/create",
+      "routine/pause",
+      "routine/delete",
+    ]);
+    expect(new Set(posts.map((post) => post.commandId)).size).toBe(3);
+    mounted.dispose();
+  });
+
+  test("surfaces a refusal instead of throwing away the reason", async () => {
+    const mounted = mount({
+      hostedRequest: () =>
+        Promise.reject(new Error("cron expression must have five fields")),
+    });
+    await mounted.state.value.load("scout");
+    expect(mounted.state.value.error).toBe(
+      "cron expression must have five fields",
+    );
+    mounted.dispose();
+  });
+
+  test("loads a run log on demand", async () => {
+    const mounted = mount();
+    await mounted.state.value.loadRuns("scout", "brief");
+    expect(mounted.state.value.runs.brief).toEqual([]);
+    mounted.dispose();
+  });
+
+  test("run now posts routine/run and reloads the Routine and its log", async () => {
+    const mounted = mount({
+      hostedRequest: (path, method, body) => {
+        if (method === "POST") {
+          return Promise.resolve({
+            schemaVersion: 1,
+            commandId: (JSON.parse(body ?? "{}") as { commandId: string })
+              .commandId,
+            status: "fired",
+            routineId: "brief",
+            fireId: "rf-brief-manual-cmd",
+          });
+        }
+        if (path.endsWith("/runs")) {
+          return Promise.resolve({
+            schemaVersion: 1,
+            botId: "scout",
+            routineId: "brief",
+            entries: [
+              {
+                schemaVersion: 1,
+                entryId: "rf-brief-manual-cmd-entry",
+                runId: "rf-brief-manual-cmd",
+                trigger: "manual",
+                status: "running",
+                startedAt: "2026-08-31T00:00:00.000Z",
+              },
+            ],
+          });
+        }
+        return Promise.resolve({
+          schemaVersion: 1,
+          botId: "scout",
+          routines: [{ ...ROUTINE, nextRunAt: "2026-09-01T21:00:00.000Z" }],
+        });
+      },
+    });
+
+    await mounted.state.value.runNow("scout", "brief");
+    expect(mounted.state.value.error).toBeUndefined();
+    // The Routine came back with the moment the scheduler armed on.
+    expect(mounted.state.value.routines[0]?.nextRunAt).toBe(
+      "2026-09-01T21:00:00.000Z",
+    );
+    expect(mounted.state.value.runs.brief?.[0]).toMatchObject({
+      trigger: "manual",
+      status: "running",
+    });
+    mounted.dispose();
+  });
+});

package/src/client/index.ts

@@ -0,0 +1,289 @@
+/// <reference path="../env.d.ts" />
+
+// The Routines hosted client Contribution.
+//
+// "The hosted client renders backend state and submits commands. It does not
+// become an alternate authority." Every write here is one `POST` of one
+// versioned command with its own idempotency key, and every read is decoded at
+// the seam before a component sees it.
+import type { ClientPlugin } from "@frockbot/client-core";
+import { ref } from "vue";
+import {
+  decodeRoutineCommandReceiptV1,
+  decodeRoutineInboxReceiptV1,
+  decodeRoutineInboxViewV1,
+  decodeRoutineListViewV1,
+  decodeRoutineRunDetailViewV1,
+  decodeRoutineRunListViewV1,
+} from "../shared.js";
+import RoutineInboxBadge from "./RoutineInboxBadge.vue";
+import RoutinesSection from "./RoutinesSection.vue";
+import RoutinesSummary from "./RoutinesSummary.vue";
+import {
+  routinesStateKey,
+  type RoutineFormSubmissionV1,
+  type RoutinesClientState,
+} from "./state.js";
+
+function message(error: unknown, fallback: string): string {
+  return error instanceof Error ? error.message : fallback;
+}
+
+export const routinesClientPlugin: ClientPlugin = (ctx) => {
+  const request = (
+    path: string,
+    method?: "GET" | "POST",
+    body?: string,
+  ): Promise<unknown> => {
+    if (!ctx.transport.hostedRequest) {
+      throw new Error("Routines are unavailable on this client");
+    }
+    return ctx.transport.hostedRequest(path, method, body);
+  };
+  const post = async (botId: string, command: unknown) => {
+    const receipt = decodeRoutineCommandReceiptV1(
+      await request(
+        `/api/bots/${encodeURIComponent(botId)}/routines`,
+        "POST",
+        JSON.stringify(command),
+      ),
+    );
+    // A minted key is on this receipt and on nothing else — no listing returns
+    // it and no second request can. It is held only for as long as the section
+    // is open.
+    if (receipt.status === "applied" && receipt.hook) {
+      state.value.mintedHook = receipt.hook;
+    }
+    return receipt;
+  };
+  const state = ref<RoutinesClientState>({
+    routines: [],
+    runs: {},
+    runDetails: {},
+    inbox: [],
+    unacknowledged: 0,
+    loaded: false,
+    busy: false,
+    async load(botId: string) {
+      try {
+        const view = decodeRoutineListViewV1(
+          await request(`/api/bots/${encodeURIComponent(botId)}/routines`),
+        );
+        state.value.botId = botId;
+        state.value.routines = view.routines;
+        state.value.loaded = true;
+        state.value.error = undefined;
+      } catch (error) {
+        state.value.error = message(error, "Could not load Routines");
+      }
+    },
+    async loadRuns(botId: string, routineId: string) {
+      try {
+        const view = decodeRoutineRunListViewV1(
+          await request(
+            `/api/bots/${encodeURIComponent(botId)}/routines/${encodeURIComponent(routineId)}/runs`,
+          ),
+        );
+        state.value.runs = { ...state.value.runs, [routineId]: view.entries };
+        state.value.error = undefined;
+      } catch (error) {
+        state.value.error = message(error, "Could not load the run log");
+      }
+    },
+    async loadRun(botId: string, routineId: string, runId: string) {
+      try {
+        const view = decodeRoutineRunDetailViewV1(
+          await request(
+            `/api/bots/${encodeURIComponent(botId)}/routines/${encodeURIComponent(routineId)}/runs/${encodeURIComponent(runId)}`,
+          ),
+        );
+        state.value.runDetails = { ...state.value.runDetails, [runId]: view };
+        state.value.error = undefined;
+      } catch (error) {
+        state.value.error = message(error, "Could not load the run");
+      }
+    },
+    async loadInbox(botId: string) {
+      try {
+        const view = decodeRoutineInboxViewV1(
+          await request(
+            `/api/bots/${encodeURIComponent(botId)}/routines/inbox`,
+          ),
+        );
+        state.value.inbox = view.entries;
+        state.value.unacknowledged = view.unacknowledged;
+        state.value.error = undefined;
+      } catch (error) {
+        state.value.error = message(error, "Could not load the inbox");
+      }
+    },
+    async acknowledgeInbox(botId: string, entryIds: string[]) {
+      state.value.busy = true;
+      try {
+        const receipt = decodeRoutineInboxReceiptV1(
+          await request(
+            `/api/bots/${encodeURIComponent(botId)}/routines/inbox`,
+            "POST",
+            JSON.stringify({
+              schemaVersion: 1,
+              commandId: crypto.randomUUID(),
+              botId,
+              type: "routine/acknowledge-inbox",
+              entryIds,
+            }),
+          ),
+        );
+        state.value.inbox = receipt.inbox.entries;
+        state.value.unacknowledged = receipt.inbox.unacknowledged;
+        state.value.error = undefined;
+      } catch (error) {
+        state.value.error = message(error, "Could not acknowledge the inbox");
+      } finally {
+        state.value.busy = false;
+      }
+    },
+    async save(botId: string, submission: RoutineFormSubmissionV1) {
+      state.value.busy = true;
+      try {
+        await post(botId, {
+          schemaVersion: 1,
+          type: submission.routineId ? "routine/update" : "routine/create",
+          commandId: crypto.randomUUID(),
+          botId,
+          ...(submission.routineId ? { routineId: submission.routineId } : {}),
+          name: submission.name,
+          prompt: submission.prompt,
+          ...(submission.schedule === undefined
+            ? {}
+            : { schedule: submission.schedule }),
+          ...(submission.trigger === undefined
+            ? {}
+            : { trigger: submission.trigger }),
+          timezone: submission.timezone,
+        });
+        await state.value.load(botId);
+      } catch (error) {
+        state.value.error = message(error, "Could not save the Routine");
+        throw error;
+      } finally {
+        state.value.busy = false;
+      }
+    },
+    async setEnabled(botId: string, routineId: string, enabled: boolean) {
+      state.value.busy = true;
+      try {
+        await post(botId, {
+          schemaVersion: 1,
+          type: enabled ? "routine/resume" : "routine/pause",
+          commandId: crypto.randomUUID(),
+          botId,
+          routineId,
+        });
+        await state.value.load(botId);
+      } catch (error) {
+        state.value.error = message(error, "Could not change the Routine");
+      } finally {
+        state.value.busy = false;
+      }
+    },
+    dismissHook() {
+      state.value.mintedHook = undefined;
+    },
+    async rotateKey(botId: string, routineId: string) {
+      state.value.busy = true;
+      try {
+        await post(botId, {
+          schemaVersion: 1,
+          type: "routine/rotate-key",
+          commandId: crypto.randomUUID(),
+          botId,
+          routineId,
+        });
+        await state.value.load(botId);
+      } catch (error) {
+        state.value.error = message(error, "Could not mint a webhook key");
+      } finally {
+        state.value.busy = false;
+      }
+    },
+    async revokeKey(botId: string, routineId: string) {
+      state.value.busy = true;
+      try {
+        state.value.mintedHook = undefined;
+        await post(botId, {
+          schemaVersion: 1,
+          type: "routine/revoke-key",
+          commandId: crypto.randomUUID(),
+          botId,
+          routineId,
+        });
+        await state.value.load(botId);
+      } catch (error) {
+        state.value.error = message(error, "Could not revoke the webhook key");
+      } finally {
+        state.value.busy = false;
+      }
+    },
+    async runNow(botId: string, routineId: string) {
+      state.value.busy = true;
+      try {
+        await post(botId, {
+          schemaVersion: 1,
+          type: "routine/run",
+          commandId: crypto.randomUUID(),
+          botId,
+          routineId,
+        });
+        await state.value.load(botId);
+        await state.value.loadRuns(botId, routineId);
+      } catch (error) {
+        state.value.error = message(error, "Could not run the Routine");
+      } finally {
+        state.value.busy = false;
+      }
+    },
+    async remove(botId: string, routineId: string) {
+      state.value.busy = true;
+      try {
+        await post(botId, {
+          schemaVersion: 1,
+          type: "routine/delete",
+          commandId: crypto.randomUUID(),
+          botId,
+          routineId,
+        });
+        await state.value.load(botId);
+      } catch (error) {
+        state.value.error = message(error, "Could not delete the Routine");
+      } finally {
+        state.value.busy = false;
+      }
+    },
+  });
+
+  return [
+    ctx.provide(routinesStateKey, state),
+    ctx.slot({
+      slot: "frockbot.bot-settings-sections",
+      order: 10,
+      component: RoutinesSection,
+    }),
+    // The header is where a completion that never spoke becomes visible: an
+    // automation Turn cannot reach the transcript, so the badge is the only
+    // thing that says a firing finished.
+    ctx.slot({
+      slot: "frockbot.header-actions",
+      order: 20,
+      component: RoutineInboxBadge,
+    }),
+    // The default Bot panel gets the glance; the section above stays the place a
+    // Routine is written.
+    ctx.slot({
+      slot: "frockbot.bot-panel-sections",
+      order: 10,
+      component: RoutinesSummary,
+    }),
+  ];
+};
+
+export default routinesClientPlugin;

package/src/client/state.ts

@@ -0,0 +1,65 @@
+import type { InjectionKey, Ref } from "vue";
+import type {
+  RoutineHookMintV1,
+  RoutineInboxEntryViewV1,
+  RoutineRunDetailViewV1,
+  RoutineRunEntryViewV1,
+  RoutineTriggerV1,
+  RoutineViewV1,
+} from "../shared.js";
+
+/** What the create/edit form submits. One of `schedule` or `trigger`, never both. */
+export interface RoutineFormSubmissionV1 {
+  routineId?: string;
+  name: string;
+  prompt: string;
+  schedule?: string;
+  trigger?: RoutineTriggerV1;
+  timezone: string;
+}
+
+export interface RoutinesClientState {
+  /** The Bot the loaded Routines belong to; nothing is shown for another. */
+  botId?: string;
+  routines: RoutineViewV1[];
+  /** Run logs by Routine, loaded on demand when a log is opened. */
+  runs: Record<string, RoutineRunEntryViewV1[]>;
+  /**
+   * One automation run's events, by run id, loaded when the reader opens it.
+   * An automation Turn is not in the transcript, so this is the only read of
+   * one and it is read-only.
+   */
+  runDetails: Record<string, RoutineRunDetailViewV1>;
+  /** The completion inbox, newest first, and what the header badge shows. */
+  inbox: RoutineInboxEntryViewV1[];
+  unacknowledged: number;
+  loaded: boolean;
+  busy: boolean;
+  error?: string;
+  load(botId: string): Promise<void>;
+  loadRuns(botId: string, routineId: string): Promise<void>;
+  loadRun(botId: string, routineId: string, runId: string): Promise<void>;
+  loadInbox(botId: string): Promise<void>;
+  /** Acknowledge entries; an empty list acknowledges all of them. */
+  acknowledgeInbox(botId: string, entryIds: string[]): Promise<void>;
+  save(botId: string, submission: RoutineFormSubmissionV1): Promise<void>;
+  setEnabled(botId: string, routineId: string, enabled: boolean): Promise<void>;
+  remove(botId: string, routineId: string): Promise<void>;
+  /** Ask for one firing now. It is queued; the alarm runs it. */
+  runNow(botId: string, routineId: string): Promise<void>;
+  /**
+   * The webhook key most recently minted in this session, and the only place it
+   * is ever readable. It is not persisted anywhere on the client and cannot be
+   * fetched again: rotating is the only way to see a key twice.
+   */
+  mintedHook?: RoutineHookMintV1;
+  /** Mint a fresh key, retiring the one before it. */
+  rotateKey(botId: string, routineId: string): Promise<void>;
+  /** Retire the key without minting another. Deliveries then answer 401. */
+  revokeKey(botId: string, routineId: string): Promise<void>;
+  /** Forget the key on screen. */
+  dismissHook(): void;
+}
+
+export const routinesStateKey: InjectionKey<Ref<RoutinesClientState>> =
+  Symbol("routines-state");