@frockbot/plugin-routines 0.3.8 → 0.3.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-routines",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "private": false,
   "type": "module",
   "exports": {
@@ -32,12 +32,12 @@
     "typecheck": "vue-tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/client-core": "0.3.8",
-    "@frockbot/client-ui": "0.3.8",
-    "@frockbot/configuration-core": "0.3.8",
-    "@frockbot/kernel-agent-loop": "0.3.8",
-    "@frockbot/kernel-contracts": "0.3.8",
-    "@frockbot/plugin-shell": "0.3.8",
+    "@frockbot/client-core": "0.3.9",
+    "@frockbot/client-ui": "0.3.9",
+    "@frockbot/configuration-core": "0.3.9",
+    "@frockbot/kernel-agent-loop": "0.3.9",
+    "@frockbot/kernel-contracts": "0.3.9",
+    "@frockbot/plugin-shell": "0.3.9",
     "cordis": "4.0.0-rc.8",
     "croner": "10.0.1",
     "vue": "3.5.41"

package/src/agent.test.ts

@@ -180,6 +180,97 @@ describe("routine_manage", () => {
   });
 });
 
+// A Bot paused a User's Routine in a Turn about sheep farming: no approval, no
+// confirmation, nothing in the transcript. A Routine the User made is theirs.
+describe("a Routine the User created", () => {
+  async function seeded() {
+    const seam = host();
+    await seam.store.execute(
+      {
+        schemaVersion: 1,
+        type: "routine/create",
+        commandId: "cmd-user",
+        botId: "scout",
+        routineId: "theirs",
+        name: "Minute ping",
+        prompt: "Say ping.",
+        schedule: "@every 1m",
+        timezone: "UTC",
+      },
+      { kind: "user" },
+    );
+    return seam;
+  }
+
+  for (const action of ["pause", "delete", "update"] as const) {
+    test(`refuses ${action} when the User did not ask`, async () => {
+      const seam = await seeded();
+      const tool = createRoutineManageTool({ ...seam, writer: WRITER });
+
+      const result = await tool.execute(
+        {
+          action,
+          routineId: "theirs",
+          ...(action === "update" ? { prompt: "Say pong." } : {}),
+        },
+        CONTEXT,
+      );
+
+      expect(result.isError).toBe(true);
+      expect(result.content).toContain("created by the User");
+      expect(result.content).toContain("userAsked: true");
+      const listed = await seam.list();
+      expect(listed.routines[0]).toMatchObject({
+        enabled: true,
+        prompt: "Say ping.",
+        createdBy: { kind: "user" },
+      });
+    });
+  }
+
+  test("pauses it once the User has asked", async () => {
+    const seam = await seeded();
+    const tool = createRoutineManageTool({ ...seam, writer: WRITER });
+
+    const result = await tool.execute(
+      { action: "pause", routineId: "theirs", userAsked: true },
+      CONTEXT,
+    );
+
+    expect(result.isError).toBe(false);
+    expect((await seam.list()).routines[0]).toMatchObject({ enabled: false });
+  });
+
+  test("leaves the Bot free to manage its own Routines", async () => {
+    const seam = host();
+    const tool = createRoutineManageTool({ ...seam, writer: WRITER });
+    await tool.execute(
+      {
+        action: "create",
+        routineId: "mine",
+        name: "Housekeeping",
+        prompt: "Tidy up.",
+        schedule: "@daily",
+      },
+      CONTEXT,
+    );
+
+    const result = await tool.execute(
+      { action: "pause", routineId: "mine" },
+      { ...CONTEXT, effectId: "tool:1:2:0" },
+    );
+
+    expect(result.isError).toBe(false);
+    expect((await seam.list()).routines[0]).toMatchObject({ enabled: false });
+  });
+
+  test("says destructive actions need the User's word", () => {
+    const tool = createRoutineManageTool({ ...host(), writer: WRITER });
+    expect(tool.description).toContain("only when the User asked you");
+    expect(tool.description).toContain("do not switch it off yourself");
+  });
+});
+
 describe("routineManageCommandV1", () => {
   test("maps a webhook trigger to the record's trigger shape", () => {
     expect(

package/src/agent.ts

@@ -102,11 +102,23 @@ const ROUTINE_MANAGE_INPUT_SCHEMA = {
       description:
         "IANA time zone the schedule is read in, such as Australia/Sydney.",
     },
+    userAsked: {
+      type: "boolean",
+      description:
+        "Set true only when the User asked you, in this conversation, to pause, edit, or delete this Routine. Required for those three actions on a Routine the User created. Never set it because a Routine looks wrong to you, is failing, or is no longer useful: say so and let the User decide.",
+    },
   },
   required: ["action"],
   additionalProperties: false,
 } as const;
 
+/** The actions that switch off or overwrite something already running. */
+const DESTRUCTIVE_ROUTINE_ACTIONS = new Set<RoutineManageActionV1>([
+  "pause",
+  "update",
+  "delete",
+]);
+
 interface RoutineManageInputV1 {
   action: RoutineManageActionV1;
   routineId?: string;
@@ -115,6 +127,7 @@ interface RoutineManageInputV1 {
   schedule?: string;
   trigger?: "webhook";
   timezone?: string;
+  userAsked?: boolean;
 }
 
 function decodeRoutineManageInputV1(input: unknown): RoutineManageInputV1 {
@@ -130,6 +143,7 @@ function decodeRoutineManageInputV1(input: unknown): RoutineManageInputV1 {
     "schedule",
     "trigger",
     "timezone",
+    "userAsked",
   ]);
   for (const key of Object.keys(value)) {
     if (!allowed.has(key)) {
@@ -153,6 +167,9 @@ function decodeRoutineManageInputV1(input: unknown): RoutineManageInputV1 {
   if (value.trigger !== undefined && value.trigger !== "webhook") {
     throw new RoutineDecodeError('routine_manage trigger must be "webhook"');
   }
+  if (value.userAsked !== undefined && typeof value.userAsked !== "boolean") {
+    throw new RoutineDecodeError("routine_manage userAsked must be a boolean");
+  }
   return {
     action,
     ...(optional("routineId") === undefined
@@ -169,6 +186,9 @@ function decodeRoutineManageInputV1(input: unknown): RoutineManageInputV1 {
     ...(optional("timezone") === undefined
       ? {}
       : { timezone: optional("timezone")! }),
+    ...(value.userAsked === undefined
+      ? {}
+      : { userAsked: value.userAsked as boolean }),
   };
 }
 
@@ -239,6 +259,28 @@ export function routineManageCommandV1(
   });
 }
 
+/**
+ * Whether the User, rather than this Bot, created the Routine.
+ *
+ * A listing that cannot be read answers `true`: not knowing who owns a Routine
+ * is a reason to ask, not a reason to switch it off. A Routine that is not in
+ * the listing at all is gone, and the command below will say so properly.
+ */
+async function userAuthoredRoutineV1(
+  host: RoutinesRuntimeHostV1,
+  routineId: string,
+): Promise<boolean> {
+  try {
+    const listing = await host.list();
+    const routine = listing.routines.find(
+      (candidate) => candidate.routineId === routineId,
+    );
+    return routine === undefined ? false : routine.createdBy.kind === "user";
+  } catch {
+    return true;
+  }
+}
+
 function refusal(reason: string): { content: string; isError: boolean } {
   return { content: `routine_manage was refused: ${reason}`, isError: true };
 }
@@ -257,6 +299,10 @@ export function createRoutineManageTool(
       "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}.`,
+      "Pausing, editing, or deleting a Routine the User created switches off something they set up,",
+      "so do it only when the User asked you to in this conversation, and pass userAsked: true when they did.",
+      "If a Routine of theirs is failing or looks wrong, tell them and let them decide — do not switch it off yourself.",
+      "Say in your reply whatever you changed.",
     ].join(" "),
     inputSchema: ROUTINE_MANAGE_INPUT_SCHEMA as unknown as Record<
       string,
@@ -272,15 +318,32 @@ export function createRoutineManageTool(
       }
     },
     execute: async (input: unknown, context: ToolExecutionContext) => {
+      let decoded: RoutineManageInputV1;
       let command: RoutineCommandV1;
       try {
-        command = routineManageCommandV1(decodeRoutineManageInputV1(input), {
+        decoded = decodeRoutineManageInputV1(input);
+        command = routineManageCommandV1(decoded, {
           botId: host.botId,
           commandId: routineToolCommandIdV1(context.effectId),
         });
       } catch (error) {
         return refusal(error instanceof Error ? error.message : String(error));
       }
+      // A Bot paused a User's Routine in a Turn about sheep farming, with no
+      // approval, no confirmation, and nothing in the transcript saying so.
+      // The User's own Routines are theirs: switching one off, or rewriting
+      // it, needs the User to have asked for it in this conversation. The
+      // Bot's own Routines it may manage freely — those are its housekeeping.
+      if (
+        DESTRUCTIVE_ROUTINE_ACTIONS.has(decoded.action) &&
+        decoded.userAsked !== true &&
+        decoded.routineId !== undefined &&
+        (await userAuthoredRoutineV1(host, decoded.routineId))
+      ) {
+        return refusal(
+          `Routine ${decoded.routineId} was created by the User. Ask them before you ${decoded.action === "update" ? "change" : decoded.action} it, and call this again with userAsked: true once they say so.`,
+        );
+      }
       const writer: RoutineWriterV1 = {
         kind: "bot",
         botId: host.botId,

package/src/client/RoutineInboxBadge.vue

@@ -82,6 +82,10 @@ function acknowledge(entryIds: string[]): void {
           <p class="routine-inbox__text">{{ entry.text }}</p>
           <footer class="routine-inbox__meta">
             <span>{{ entry.createdAt }}</span>
+            <!-- One thing going wrong repeatedly is one entry and a count. -->
+            <span v-if="(entry.repeatCount ?? 1) > 1"
+              >Happened {{ entry.repeatCount }} times</span
+            >
             <UiButton
               v-if="!entry.acknowledged"
               variant="ghost"

package/src/inbox-store.ts

@@ -82,6 +82,8 @@ export interface RoutineTerminalInputV1 {
   /** The Turn's own response text, used when it handed off nothing. */
   responseText?: string;
   now: string;
+  /** The firing did not work; the entry is a complaint, not a completion. */
+  failure?: true;
   read<T>(key: string): Promise<T | undefined>;
 }
 
@@ -129,6 +131,7 @@ export async function routineTerminalRecordsV1(
     createdAt: input.now,
     acknowledged: false,
     ...(input.handoff === undefined ? {} : { wakeId }),
+    ...(input.failure === undefined ? {} : { failure: input.failure }),
   };
   const records: Record<string, unknown> = {
     [routineInboxKeyV1(inbox.nextSeq)]: entry,

package/src/inbox.ts

@@ -58,6 +58,42 @@ export function subagentAttributionV1(description: string): string {
 
 /** Longest hand-off an inbox entry or a pending wake carries. */
 export const ROUTINE_INBOX_TEXT_MAX = 4_000;
+
+/**
+ * What a person is told a firing failed for.
+ *
+ * A failure summary is whatever the kernel had to hand — the run's `failure`
+ * string, a thrown message, a lease timeout. Some of those are sentences a
+ * person can act on ("the model is unavailable"); others are invariants
+ * addressed to this codebase, like `tool occurrence "tool:1:1:1" was not
+ * settled before step end`, which told a User nothing except that something
+ * they cannot see is broken. The raw string stays on the run-log row, which is
+ * where an operator looks; what reaches the inbox and the notification is a
+ * sentence.
+ *
+ * The test is deliberately coarse: anything carrying the shape of an internal
+ * identifier — a quoted occurrence, a `foo:1:2:3` coordinate, a stack frame —
+ * is not for a person. Everything else is passed through, because a provider
+ * saying "rate limited" is exactly what the User wants to read.
+ */
+const INTERNAL_FAILURE_MARKERS = [
+  /\btool occurrence\b/i,
+  /\b[a-z-]+:\d+:\d+:\d+\b/i,
+  /\bat [\w$.]+ \(/,
+  /\bschemaVersion\b/,
+  /\boutcome model-error\b/i,
+  /\binvariant\b/i,
+];
+
+/** The sentence a person reads instead of a kernel string. Never empty. */
+export function routineFailureSentenceV1(summary: string | undefined): string {
+  const text = (summary ?? "").trim();
+  if (text.length === 0) return "It stopped without saying why.";
+  if (INTERNAL_FAILURE_MARKERS.some((marker) => marker.test(text))) {
+    return "Something inside FrockBot went wrong; the run log has the details.";
+  }
+  return text;
+}
 /** Longest title a pending wake carries. */
 export const ROUTINE_WAKE_TITLE_MAX = 200;
 
@@ -78,6 +114,23 @@ export interface RoutineInboxEntryV1 {
   /** Present when the Turn also handed off, naming the wake it queued. */
   wakeId?: string;
   acknowledgedAt?: string;
+  /**
+   * How many firings this entry stands for. Absent means one.
+   *
+   * A Routine that fails every minute wrote a fresh entry every minute, and a
+   * user who had not looked in an hour found sixty rows of the same sentence.
+   * Consecutive failures of the same Routine with the same failure fold into
+   * the entry already there and raise this count, so the inbox says what is
+   * wrong once and how often it has happened.
+   */
+  repeatCount?: number;
+  /**
+   * Set when the entry is a firing that did not work. A completion is routine
+   * and deliberately badges nothing; a failure is the Bot telling its User
+   * that an automation they set up has stopped, which is exactly what the
+   * sidebar badge is for.
+   */
+  failure?: true;
   /**
    * What produced this entry. Absent means `routine`; `routineId` then carries
    * the task id, because the field names the automation the entry came from
@@ -210,7 +263,7 @@ export function decodeRoutineInboxEntryV1(
       "createdAt",
       "acknowledged",
     ],
-    ["wakeId", "acknowledgedAt", "source"],
+    ["wakeId", "acknowledgedAt", "source", "repeatCount", "failure"],
     label,
   );
   if (candidate.schemaVersion !== 1) {
@@ -249,9 +302,25 @@ export function decodeRoutineInboxEntryV1(
     ...(candidate.source === undefined
       ? {}
       : { source: completionSourceV1(candidate.source, `${label} source`) }),
+    ...(candidate.repeatCount === undefined
+      ? {}
+      : {
+          repeatCount: routineRepeatCountV1(
+            candidate.repeatCount,
+            `${label} repeatCount`,
+          ),
+        }),
+    ...(candidate.failure === undefined ? {} : { failure: true as const }),
   };
 }
 
+function routineRepeatCountV1(value: unknown, label: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 1) {
+    throw new RoutineDecodeError(`${label} is invalid`);
+  }
+  return value as number;
+}
+
 export function decodePendingBotInputV1(
   value: unknown,
   label = "pending Bot input",

package/src/scheduler.test.ts

@@ -759,6 +759,119 @@ describe("a failed firing", () => {
   });
 });
 
+describe("what a failing Routine tells the person", () => {
+  // The inbox entry, the run-log summary and the notification all carried
+  // `tool occurrence "tool:1:1:1" was not settled before step end`.
+  test("writes a sentence, and keeps the kernel string on the run log", async () => {
+    const { storage, time, scheduler, store, create } = harness({
+      start: "2026-01-01T00:00:00.000Z",
+      schedule: "@every 1m",
+    });
+    await store.execute(create, USER);
+    time.set("2026-01-01T00:01:00.000Z");
+    const raw =
+      'Bot turn ended with outcome model-error: tool occurrence "tool:1:1:1" was not settled before step end';
+    await drain(scheduler, { status: "failed", summary: raw });
+
+    const entries = await new RoutineInboxStore(storage, {
+      now: time.now,
+    }).list();
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.text).toBe(
+      '"Morning brief" did not run: Something inside FrockBot went wrong; the run log has the details.',
+    );
+    expect(entries[0]?.text).not.toContain("tool occurrence");
+    // The operator's copy is untouched.
+    const runs = await storage.list<unknown>({ prefix: ROUTINE_RUN_PREFIX });
+    expect(
+      [...runs.values()].map((row) => decodeRoutineRunEntryV1(row).summary),
+    ).toEqual([raw]);
+  });
+
+  test("a provider's own words reach the person unchanged", async () => {
+    const { storage, time, scheduler, store, create } = harness({
+      start: "2026-01-01T00:00:00.000Z",
+      schedule: "@every 1m",
+    });
+    await store.execute(create, USER);
+    time.set("2026-01-01T00:01:00.000Z");
+    await drain(scheduler, {
+      status: "failed",
+      summary: "the model provider is rate limiting this account",
+    });
+
+    const entries = await new RoutineInboxStore(storage, {
+      now: time.now,
+    }).list();
+    expect(entries[0]?.text).toBe(
+      '"Morning brief" did not run: the model provider is rate limiting this account',
+    );
+  });
+
+  // Sixty rows of the same sentence is not sixty things being wrong.
+  test("folds repeats of one failure into a single entry with a count", async () => {
+    const { storage, time, scheduler, store, create } = harness({
+      start: "2026-01-01T00:00:00.000Z",
+      schedule: "@every 1m",
+    });
+    await store.execute(create, USER);
+    const failure = { status: "failed" as const, summary: "flaked" };
+    for (const minute of ["00:01", "02:00", "04:00"]) {
+      time.set(`2026-01-01T${minute}:00.000Z`);
+      await drain(scheduler, failure);
+    }
+
+    const entries = await new RoutineInboxStore(storage, {
+      now: time.now,
+    }).list();
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.repeatCount).toBe(3);
+    expect(entries[0]?.createdAt).toBe("2026-01-01T04:00:00.000Z");
+    // Every firing still has its own run-log row; only the inbox collapses.
+    expect(
+      (await storage.list<unknown>({ prefix: ROUTINE_RUN_PREFIX })).size,
+    ).toBeGreaterThanOrEqual(3);
+  });
+
+  test("a different failure gets its own entry", async () => {
+    const { storage, time, scheduler, store, create } = harness({
+      start: "2026-01-01T00:00:00.000Z",
+      schedule: "@every 1m",
+    });
+    await store.execute(create, USER);
+    time.set("2026-01-01T00:01:00.000Z");
+    await drain(scheduler, { status: "failed", summary: "flaked" });
+    time.set("2026-01-01T02:00:00.000Z");
+    await drain(scheduler, { status: "failed", summary: "the disk is full" });
+
+    const entries = await new RoutineInboxStore(storage, {
+      now: time.now,
+    }).list();
+    expect(entries).toHaveLength(2);
+    expect(entries.every((entry) => entry.repeatCount === undefined)).toBe(
+      true,
+    );
+  });
+
+  // The panel showed a "Next run" five minutes in the past that never moved.
+  test("reports a backed-off Routine's next run in the future", async () => {
+    const { storage, time, scheduler, store, create } = harness({
+      start: "2026-01-01T00:00:00.000Z",
+      schedule: "@every 1m",
+    });
+    await store.execute(create, USER);
+    time.set("2026-01-01T00:01:00.000Z");
+    await drain(scheduler, { status: "failed", summary: "flaked" });
+
+    const next = (await scheduler.nextRuns()).get("brief");
+    expect(next).toBeDefined();
+    expect(Date.parse(next!)).toBeGreaterThan(time.now().getTime());
+    expect(next).toBe(
+      new Date(routineDeadlineV1(await state(storage))).toISOString(),
+    );
+  });
+});
+
 describe("an undecodable Routine record", () => {
   test("degrades that one Routine, never the whole object", async () => {
     const { storage, time, scheduler, store, create } = harness({

package/src/scheduler.ts

@@ -35,6 +35,11 @@ import {
   type RoutineFireV1,
   type RoutineScheduleStateV1,
 } from "./firing.js";
+import {
+  decodeRoutineInboxEntryV1,
+  routineFailureSentenceV1,
+  type RoutineInboxEntryV1,
+} from "./inbox.js";
 import { routineTerminalRecordsV1 } from "./inbox-store.js";
 import {
   decodeRoutineRecordV1,
@@ -53,6 +58,7 @@ import {
   ROUTINE_DEFERRAL_MS,
   ROUTINE_FIRE_LEASE_MS,
   ROUTINE_FIRE_PREFIX,
+  ROUTINE_INBOX_PREFIX,
   ROUTINE_FAILURE_BACKOFF_MS,
   ROUTINE_FAILURE_PAUSE_AFTER,
   ROUTINE_FIRE_TIMEOUT_MS,
@@ -437,7 +443,14 @@ export class RoutineScheduler {
   async nextRuns(): Promise<Map<string, string>> {
     const next = new Map<string, string>();
     for (const { record, state } of await this.#clocks(this.#storage)) {
-      next.set(record.routineId, new Date(state.dueAt).toISOString());
+      // The deadline, not the raw due time: a Routine held back by a deferral
+      // or a failure backoff is next owed a firing when the hold ends. Reading
+      // `dueAt` alone showed a "Next run" that had already gone past and never
+      // moved, for as long as the backoff lasted.
+      next.set(
+        record.routineId,
+        new Date(routineDeadlineV1(state)).toISOString(),
+      );
     }
     return next;
   }
@@ -798,14 +811,32 @@ export class RoutineScheduler {
   ): Promise<void> {
     const name = await this.#routineName(transaction, fire.routineId);
     const verb = outcome.status === "cancelled" ? "was stopped" : "did not run";
+    // The sentence, not the kernel string: the raw summary is on the run-log
+    // row this same transaction writes, which is where an operator looks.
+    const text = `"${name}" ${verb}: ${routineFailureSentenceV1(outcome.summary)}`;
+    // The same Routine failing the same way every minute is one thing that is
+    // wrong, not sixty. It folds into the entry already at the head of the
+    // inbox, which keeps its place in the order and gains a count.
+    const repeated = await this.#collapsibleFailure(
+      transaction,
+      fire.routineId,
+      text,
+    );
+    if (repeated) {
+      await transaction.put(repeated.key, {
+        ...repeated.entry,
+        runId: fire.fireId,
+        createdAt: now,
+        repeatCount: (repeated.entry.repeatCount ?? 1) + 1,
+      } satisfies RoutineInboxEntryV1);
+      return;
+    }
     const records = await routineTerminalRecordsV1({
       runId: fire.fireId,
       routineId: fire.routineId,
       routineName: name,
-      responseText:
-        outcome.summary === undefined || outcome.summary.trim().length === 0
-          ? `"${name}" ${verb}.`
-          : `"${name}" ${verb}: ${outcome.summary}`,
+      responseText: text,
+      failure: true,
       now,
       read: (key) => transaction.get(key),
     });
@@ -815,6 +846,41 @@ export class RoutineScheduler {
     }
   }
 
+  /**
+   * The newest inbox entry, when it is an unread repeat of this same failure.
+   *
+   * Only the newest: an entry the User has already read, or one with anything
+   * in front of it, is part of a history rather than the live complaint, and
+   * rewriting it would move a row the User has already looked past.
+   */
+  async #collapsibleFailure(
+    transaction: RoutineStorageWritesV1,
+    routineId: string,
+    text: string,
+  ): Promise<{ key: string; entry: RoutineInboxEntryV1 } | undefined> {
+    const newest = await transaction.list<unknown>({
+      prefix: ROUTINE_INBOX_PREFIX,
+      limit: 1,
+    });
+    for (const [key, stored] of newest) {
+      try {
+        const entry = decodeRoutineInboxEntryV1(stored);
+        if (
+          !entry.acknowledged &&
+          entry.routineId === routineId &&
+          entry.wakeId === undefined &&
+          entry.text === text
+        ) {
+          return { key, entry };
+        }
+      } catch {
+        // An entry that cannot be read is not one to fold into.
+      }
+      return undefined;
+    }
+    return undefined;
+  }
+
   async #settleFiring(
     fire: RoutineFireV1,
     outcome: RoutineFireOutcomeV1,

package/src/shared.ts

@@ -709,6 +709,10 @@ export interface RoutineInboxEntryViewV1 {
   createdAt: string;
   acknowledged: boolean;
   acknowledgedAt?: string;
+  /** How many firings this entry stands for; absent means one. */
+  repeatCount?: number;
+  /** The firing did not work. */
+  failure?: true;
 }
 
 export interface RoutineInboxViewV1 {